---
name: architecture
description: Use when you need to understand the Pyre or Pysa codebase architecture, find where specific functionality is implemented, or navigate the source directory structure. Use when working on OCaml code, debugging type checking or taint analysis issues, or exploring the codebase.
oncalls: ['pysa']
---

# Pyre Architecture

## Type Checking Pipeline

- **Python CLI** (`client/`): Reads `.pyre_configuration`, determines flags, shells out to `pyre.bin`
- **Command dispatch** (`source/main.ml`): Routes to `Check`, `Analyze` (Pysa), `Infer`, `Server`, `CodeNavigation`, or `NoDaemonQuery`
- **Parsing** (`source/menhir_parser/`, `source/cpython_parser/`): Python source -> AST (`source/ast/`)
- **Environment building** (`source/analysis/`): Populates global type environment in parallel. All sources added at once (not recursively following imports). Builds a layered environment chain: `UnannotatedGlobalEnvironment` -> `ClassHierarchyEnvironment` -> `TypeAliasEnvironment` -> `AnnotatedGlobalEnvironment` -> `FunctionDefinitionEnvironment` -> `ErrorsEnvironment` -> `TypeEnvironment`
- **Type checking** (`source/analysis/typeCheck.ml`): Each function checked in parallel via control flow graph. Propagates parameter types through function body, checks compatibility at each operation. Never goes beyond function call boundaries.
- **Error reporting**: Results collected and returned to CLI

## Pysa (Taint Analysis) Pipeline

- **Analysis orchestrator** (`source/interprocedural_analyses/taint/taintAnalysis.ml`):  Main entrypoint of the analysis, runs the different analysis steps
- **PyrePysaApi** (`source/interprocedural/pyrePysaApi.ml`): Provides an API to query a type checker (pyre or pyrefly)
- **Class Hierarchy Graph** (`source/interprocedural/classHierarchyGraph.ml`): Builds a class hierarchy graph
- **Callables Shared Memory** (`source/interprocedural/callablesSharedMemory.ml`): Builds a mapping from callables (functions and methods) to their AST and signature
- **Call Graph** (`source/interprocedural/callGraph.ml`): Defines call graph data structures
- **Call Graph Builder** (`source/interprocedural/callGraphBuilder.ml`): Builds call graphs for all callables
- **Model parsing** (`source/interprocedural_analyses/taint/modelParser.ml`): Parses `.pysa` model files
- **Forward analysis** (`source/interprocedural_analyses/taint/forwardAnalysis.ml`): Tracks taint from sources
- **Backward analysis** (`source/interprocedural_analyses/taint/backwardAnalysis.ml`): Tracks taint to sinks
- **Configuration** (`source/interprocedural_analyses/taint/taintConfiguration.ml`): Defines rules connecting sources to sinks
- **Global Fixpoint** (`source/interprocedural/fixpointAnalysis.ml`): Implements a global fixpoint over callables
- **Model** (`source/interprocedural_analyses/taint/model.ml`): Defines a summary of the taint behavior of a function, inferred during analysis

## Key Source Directories

- `source/ast/`: Python AST representation (Expression, Statement, Source, Location, Reference)
- `source/analysis/`: Core type checker: type representation (`type.ml`), CFG, fixpoint, preprocessing, environments, type order, class hierarchy
- `source/interprocedural/`: Interprocedural framework: call graph, dependency graph, override graph, fixpoint
- `source/interprocedural_analyses/taint/`: Pysa taint analysis: sources, sinks, domains, models, rules, reporting
- `source/interprocedural_analyses/type_inference/`: Interprocedural type inference
- `source/server/`: Pyre daemon for incremental analysis
- `source/code_navigation_server/`: IDE code navigation server
- `source/command/`: OCaml CLI command implementations
- `source/buck_command/`: Buck-specific commands
- `source/buck_integration/`: Buck build system integration
- `source/service/`: Shared memory management, scheduling
- `source/domains/`: Abstract domain library (lattices for interprocedural analyses)
- `source/hack_parallel/`: Shared memory and multi-worker infrastructure (forked from Hack)
- `source/saved_state/`: Serialization for incremental analysis
- `client/`: Python CLI (`pyre` command)
- `client/commands/`: All user-facing commands (check, analyze, start, stop, infer, query, etc.)
- `client/configuration/`: `.pyre_configuration` file parsing
- `client/language_server/`: LSP protocol implementation
- `api/`: Programmatic Python API for Pyre server
- `pyre_extensions/`: Runtime Python helpers (`none_throws`, `safe_cast`, etc.)
- `tools/generate_taint_models/`: Auto-generation of Pysa taint models
- `tools/typeshed_patcher/`: Applies patches to bundled typeshed stubs
- `stubs/`: Bundled typeshed with patching mechanism
- `facebook/`: Meta-internal code (not open-sourced)

## OCaml Conventions

- Most types derive `show`, `eq`, `compare`, `to_yojson` via PPX derivers. For a type `Module.t`, `Module.show` gives a debug string.
- Debug with `Log.dump "format %s" value` and run with `pyre --noninteractive check`
- In Python test files, use `pyre_dump()`, `pyre_dump_cfg()`, `pyre_dump_locations()`, and `reveal_type(x)` to inspect Pyre's state