# astral-sh/ty architecture

> Architecture diagram of the GitHub repository astral-sh/ty, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/astral-sh/ty
- Repository: https://github.com/astral-sh/ty

## Overview

ty is a Rust-backed Python type checker and language server. The principal CLI workflow starts when a developer invokes `ty check` on a Python project: the packaged executable or Python module launcher resolves the Rust binary, which loads project configuration, analyzes source through the type-system engine, and returns diagnostics and an exit status. An editor provides a parallel LSP workflow for interactive diagnostics, navigation, completions, and fine-grained incremental updates.

Components

**Invocation and packaging**
- **Developer** — `null`: External caller that invokes `ty check` or starts language-server mode.
- **Python module launcher** — `python/ty/__main__.py`: Implements `python -m ty`; it calls binary discovery and uses `execvp` on Unix or `subprocess.run` on Windows.
- **Binary discovery** — `python/ty/_find_ty.py`: Searches Python, prefix, adjacent-installation, and user-scheme locations for the compiled `ty` executable.
- **Rust ty executable** — `ruff`: The compiled Rust product; `pyproject.toml` points maturin at the `ruff` ty crate, while the README identifies the product as both a type checker and language server.

**User-facing project interfaces**
- **Command-line interface** — `docs/reference/cli.md`: Documents commands, checking modes, output behavior, and CLI options.
- **Configuration and project support** — `docs/reference/configuration.md`: Defines the project configuration surface used to control checking behavior.
- **Python project** — `null`: External source files, packages, stubs, and configuration supplied for analysis.

**Static analysis**
- **Analysis orchestrator** — `ruff`: Rust implementation layer that coordinates project checking and connects front-end requests to semantic analysis; exact internal call structure is not sampled.
- **Type-system semantics** — `docs/features/type-system.md`: Documents narrowing, intersections, reachability, gradual typing, and other semantic rules applied during analysis.
- **Diagnostic pipeline** — `docs/features/diagnostics.md`: Defines the contextual diagnostics produced from analysis findings.
- **Incremental analysis state** — `docs/features/language-server.md`: Documents fine-grained retained analysis used to make editor updates fast; its concrete storage structures are not visible here.

**Language-server consumers**
- **Language server** — `docs/features/language-server.md`: Provides the LSP capability for diagnostics, navigation, completions, code actions, auto-imports, inlay hints, and hover information.
- **Editor client** — `null`: External VS Code, PyCharm, Neovim, or other LSP client.
- **Editor integrations** — `docs/editors.md`: Documents how supported editors connect to ty and configure the language-server capability.

Relationships

- **Developer -> Rust ty executable**: invokes `ty check`; supported by the README’s getting-started command and the compiled binary packaging.
- **Developer -> Python module launcher**: may invoke the Python module entry point; evidenced by the module’s executable guard.
- **Python module launcher -> Binary discovery**: imports and calls `find_ty_bin`.
- **Binary discovery -> Rust ty executable**: resolves the executable path from installation layouts.
- **Python module launcher -> Rust ty executable**: starts the resolved process with the original arguments, using `execvp` or a Windows subprocess.
- **Command-line interface -> Rust ty executable**: defines the documented command and option contract exposed by the executable.
- **Rust ty executable -> Python project**: reads the project’s Python sources and related analysis inputs.
- **Rust ty executable -> Configuration and project support**: applies project configuration while setting up a check.
- **Rust ty executable -> Analysis orchestrator**: dispatches CLI checking requests into the Rust analysis implementation.
- **Analysis orchestrator -> Type-system semantics**: performs semantic type evaluation according to the documented type system.
- **Analysis orchestrator -> Diagnostic pipeline**: converts analysis findings into user-facing diagnostics.
- **Rust ty executable -> Developer**: reports diagnostics and command status through the CLI.
- **Editor client -> Language server**: sends LSP requests and document updates.
- **Rust ty executable -> Language server**: hosts the language-server mode as an alternative front end to CLI checking.
- **Language server -> Analysis orchestrator**: translates editor requests into analysis operations.
- **Language server -> Incremental analysis state**: reads and updates retained analysis state for fine-grained edits.
- **Language server -> Editor client**: returns diagnostics, navigation results, completions, and other LSP responses.
- **Editor integrations -> Editor client**: supplies editor-specific setup and connection guidance.

Coverage limits

The sampled repository contains the Python launcher and packaging metadata but not the Rust source inside the `ruff` submodule. Therefore exact parser, module-resolution, configuration-loading, diagnostic-formatting, caching, and LSP-dispatch internals cannot be established. Release, documentation-generation, and PGO scripts were treated as development tooling rather than product components.

Main entry points: [`ruff`](https://github.com/astral-sh/ty/tree/main/ruff) (Rust ty Executable), [`docs/features/language-server.md`](https://github.com/astral-sh/ty/blob/main/docs/features/language-server.md) (Language Server), [`python/ty/__main__.py`](https://github.com/astral-sh/ty/blob/main/python/ty/__main__.py) (Python Module Launcher), [`python/ty/_find_ty.py`](https://github.com/astral-sh/ty/blob/main/python/ty/_find_ty.py) (Binary Discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_invocation["Invocation and Packaging"]
  node_developer(("Developer<br/>external actor"))
  node_module_launcher["Python Module Launcher<br/>[__main__.py]"]
  node_binary_discovery["Binary Discovery<br/>resolver"]
  node_rust_executable{{"Rust ty Executable"}}
end

subgraph group_interfaces["Project Interfaces"]
  node_cli["Command-Line Interface<br/>[cli.md]"]
  node_config_support["Configuration and Project Support<br/>[configuration.md]"]
  node_python_project["Python Project<br/>external project"]
end

subgraph group_analysis["Static Analysis"]
  node_analysis_orchestrator["Analysis Orchestrator"]
  node_type_semantics["Type-System Semantics<br/>semantic engine"]
  node_diagnostic_pipeline["Diagnostic Pipeline<br/>[diagnostics.md]"]
  node_incremental_state[("Incremental Analysis State<br/>state store")]
end

subgraph group_lsp["Language Server"]
  node_language_server["Language Server<br/>LSP service"]
  node_editor_client(("Editor Client<br/>external client"))
  node_editor_integrations["Editor Integrations<br/>documentation"]
end

node_developer -->|"invokes ty check"| node_rust_executable
node_developer -->|"invokes module"| node_module_launcher
node_module_launcher -->|"calls find_ty_bin"| node_binary_discovery
node_binary_discovery -->|"resolves executable"| node_rust_executable
node_module_launcher -->|"starts process"| node_rust_executable
node_cli -->|"defines contract"| node_rust_executable
node_rust_executable -->|"reads inputs"| node_python_project
node_rust_executable -->|"applies configuration"| node_config_support
node_rust_executable -->|"dispatches checking"| node_analysis_orchestrator
node_analysis_orchestrator -->|"evaluates types"| node_type_semantics
node_analysis_orchestrator -->|"creates diagnostics"| node_diagnostic_pipeline
node_rust_executable -->|"reports results"| node_developer
node_editor_client -->|"sends LSP requests"| node_language_server
node_rust_executable -->|"hosts mode"| node_language_server
node_language_server -->|"translates requests"| node_analysis_orchestrator
node_language_server -->|"updates state"| node_incremental_state
node_language_server -->|"returns LSP responses"| node_editor_client
node_editor_integrations -->|"supplies setup"| node_editor_client

click node_module_launcher "https://github.com/astral-sh/ty/blob/main/python/ty/__main__.py"
click node_binary_discovery "https://github.com/astral-sh/ty/blob/main/python/ty/_find_ty.py"
click node_rust_executable "https://github.com/astral-sh/ty/tree/main/ruff"
click node_cli "https://github.com/astral-sh/ty/blob/main/docs/reference/cli.md"
click node_config_support "https://github.com/astral-sh/ty/blob/main/docs/reference/configuration.md"
click node_analysis_orchestrator "https://github.com/astral-sh/ty/tree/main/ruff"
click node_type_semantics "https://github.com/astral-sh/ty/blob/main/docs/features/type-system.md"
click node_diagnostic_pipeline "https://github.com/astral-sh/ty/blob/main/docs/features/diagnostics.md"
click node_incremental_state "https://github.com/astral-sh/ty/blob/main/docs/features/language-server.md"
click node_language_server "https://github.com/astral-sh/ty/blob/main/docs/features/language-server.md"
click node_editor_integrations "https://github.com/astral-sh/ty/blob/main/docs/editors.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_developer,node_module_launcher,node_binary_discovery,node_rust_executable toneBlue
class node_cli,node_config_support,node_python_project toneAmber
class node_analysis_orchestrator,node_type_semantics,node_diagnostic_pipeline,node_incremental_state toneMint
class node_language_server,node_editor_client,node_editor_integrations toneRose
```

## Components

### Invocation and Packaging

Entry points and executable resolution

- **Developer**: external actor · Invokes CLI or language-server mode
- [Python Module Launcher](https://github.com/astral-sh/ty/blob/main/python/ty/__main__.py): launcher · Implements python -m ty · `python/ty/__main__.py`
- [Binary Discovery](https://github.com/astral-sh/ty/blob/main/python/ty/_find_ty.py): resolver · Finds the compiled ty executable · `python/ty/_find_ty.py`
- [Rust ty Executable](https://github.com/astral-sh/ty/tree/main/ruff): executable · Compiled type checker and language server · `ruff`

### Project Interfaces

CLI, configuration, and analyzed project inputs

- [Command-Line Interface](https://github.com/astral-sh/ty/blob/main/docs/reference/cli.md): interface · Documents commands and options · `docs/reference/cli.md`
- [Configuration and Project Support](https://github.com/astral-sh/ty/blob/main/docs/reference/configuration.md): configuration · Defines project checking configuration · `docs/reference/configuration.md`
- **Python Project**: external project · Source files, packages, stubs, and configuration

### Static Analysis

Type checking and diagnostic production

- [Analysis Orchestrator](https://github.com/astral-sh/ty/tree/main/ruff): service · Coordinates project checking and front-end requests · `ruff`
- [Type-System Semantics](https://github.com/astral-sh/ty/blob/main/docs/features/type-system.md): semantic engine · Applies documented type-system rules · `docs/features/type-system.md`
- [Diagnostic Pipeline](https://github.com/astral-sh/ty/blob/main/docs/features/diagnostics.md): pipeline · Produces contextual diagnostics · `docs/features/diagnostics.md`
- [Incremental Analysis State](https://github.com/astral-sh/ty/blob/main/docs/features/language-server.md): state store · Retains fine-grained analysis state · `docs/features/language-server.md`

### Language Server

Interactive editor analysis and LSP communication

- [Language Server](https://github.com/astral-sh/ty/blob/main/docs/features/language-server.md): LSP service · Provides interactive language features · `docs/features/language-server.md`
- **Editor Client**: external client · VS Code, PyCharm, Neovim, or another LSP client
- [Editor Integrations](https://github.com/astral-sh/ty/blob/main/docs/editors.md): documentation · Documents editor setup and connections · `docs/editors.md`

## Connections

- Developer → Rust ty Executable: invokes ty check
- Developer → Python Module Launcher: invokes module
- Python Module Launcher → Binary Discovery: calls find_ty_bin
- Binary Discovery → Rust ty Executable: resolves executable
- Python Module Launcher → Rust ty Executable: starts process · Uses execvp on Unix or subprocess.run on Windows
- Command-Line Interface → Rust ty Executable: defines contract
- Rust ty Executable → Python Project: reads inputs
- Rust ty Executable → Configuration and Project Support: applies configuration
- Rust ty Executable → Analysis Orchestrator: dispatches checking
- Analysis Orchestrator → Type-System Semantics: evaluates types
- Analysis Orchestrator → Diagnostic Pipeline: creates diagnostics
- Rust ty Executable → Developer: reports results · Returns diagnostics and command status
- Editor Client → Language Server: sends LSP requests · Includes document updates
- Rust ty Executable → Language Server: hosts mode · Provides language-server mode as an alternative front end
- Language Server → Analysis Orchestrator: translates requests
- Language Server → Incremental Analysis State: updates state · Reads and updates retained analysis state
- Language Server → Editor Client: returns LSP responses · Diagnostics, navigation, completions, and other results
- Editor Integrations → Editor Client: supplies setup · Provides editor-specific connection guidance
