# astral-sh/rye architecture

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

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

## Overview

##### Project Type and Purpose
- Rye is a cross-platform, command-line application written in Rust (with an accompanying Python “rye-devtools” package) that provides a one-stop solution for managing Python installations, virtual environments, dependencies, builds, formatting, linting, and publishing.
- It acts as a CLI wrapper around multiple subsystems and external tools (Indygreg Python builds, virtualenv, ruff, build, twine, pip-tools, etc.), orchestrating them under a unified interface.

##### Top-Level Components
- CLI Frontend (rye/src/cli): parses subcommands (`add`, `install`, `lock`, `fmt`, `publish`, etc.) and dispatches to the core engine.
- Core Engine Modules (rye/src/*):
– config.rs: loads and persists global and project-specific settings.
– installer.rs: downloads and installs Python runtimes (Indygreg builds, PyPy).
– lock.rs & sync.rs: dependency resolution (via uv, unearth, pip-tools) and virtualenv creation.
– build.rs: wraps the `build` package for wheel creation.
– publish.rs: wraps `twine` for package publishing.
– fmt.rs & lint.rs: shells out to `ruff`.
– pyproject.rs: reads/writes pyproject.toml data.
– sources/*: generated lists of Python/UV download URLs.
– templates/*: Jinja2-style cargo/python project scaffolding.
- Process Shims & TUI (rye/src/shim.rs, rye/src/tui.rs): generates platform-specific wrapper scripts and/or an interactive interface.
- Python Devtools (rye-devtools/): a small Python package exposing helper commands used during development of Rye and optionally by advanced users.
- Documentation Site (docs/, mkdocs.yml): MkDocs-based static site for user guides, reference, and examples.
- CI/CD Workflows (.github/workflows): linting, formatting (rustfmt, clippy, python-lint), testing (Rust & Python tests), spelling, release automation.

##### External Dependencies and Services
- Python distribution sources (Indygreg, PyPy)
- PyPI (package upload via Twine, dependency fetch via UV and pip)
- GitHub (source repo hosting, Actions, issues, discussions, releases)
- Third-party binaries: ruff, build, virtualenv, uv, unearth, pip-tools

##### Architectural Patterns and Principles
- Modular Command Dispatcher – each CLI subcommand implemented in its own module.
- Separation of Concerns – distinct modules for installation, locking, building, publishing, formatting, etc.
- Code Generation – embedding generated download tables and scaffolding templates.
- Adapter Pattern – wrapping external tools (ruff, build, twine) behind a uniform CLI.
- Cross-Platform Shims – abstracting OS-specific script generation.
- Plugin-Style Extensibility – templates and hooks allow user customization and future extension.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CI/CD Pipeline
    CI["CI/CD Pipeline<br/>(GitHub Actions)"]:::cicd
    CI -->|"runs on repo"| Repo["Rye Repository"]

    %% User invocation
    User["User"]:::external
    User -->|"invokes CLI"| CLIParser

    %% Rye Binary
    subgraph "Rye Binary" 
        direction TB
        CLIParser["CLI Parser & Dispatcher<br/>(rye/src/cli)"]:::cli
        Config["Config Manager<br/>(rye/src/config.rs)"]:::core
        Installer["Installer Module<br/>(rye/src/installer.rs)"]:::core
        LockM["Lock Module<br/>(rye/src/lock.rs)"]:::core
        SyncM["Sync Module<br/>(rye/src/sync.rs)"]:::core
        BuildM["Build Module<br/>(rye/src/cli/build.rs)"]:::adapter
        PublishM["Publish Module<br/>(rye/src/cli/publish.rs)"]:::adapter
        LintFmt["Lint/Format Module<br/>(rye/src/cli/fmt.rs & lint.rs)"]:::adapter
        ShimTUI["Shim Generator & TUI<br/>(rye/src/cli/shim.rs & tui.rs)"]:::core
        Template["Template Engine<br/>(rye/src/templates)"]:::core
        PyProj["PyProject Manager<br/>(rye/src/pyproject.rs)"]:::core
        Sources["Sources (code-gen)<br/>(rye/src/sources)"]:::core
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        PyDist["Python Dist. Servers"]:::external
        PyPI["PyPI"]:::external
        VirtualEnv["virtualenv"]:::external
        Ruff["ruff"]:::external
        BuildTool["build"]:::external
        Twine["twine"]:::external
        PipTools["pip-tools"]:::external
    end

    %% Devtools and Docs
    Devtools["rye-devtools<br/>(rye-devtools)"]:::devtools
    Docs["Documentation Site<br/>(docs/)"]:::docs

    %% Relationships
    CLIParser -->|"loads settings"| Config
    CLIParser -->|"runs subcommand"| Installer
    CLIParser -->|"runs subcommand"| LockM
    CLIParser -->|"runs subcommand"| SyncM
    CLIParser -->|"runs subcommand"| BuildM
    CLIParser -->|"runs subcommand"| PublishM
    CLIParser -->|"runs subcommand"| LintFmt
    CLIParser -->|"runs subcommand"| ShimTUI
    CLIParser -->|"runs subcommand"| Template
    CLIParser -->|"reads/writes"| PyProj
    Installer -->|"uses download URLs"| Sources
    Installer -->|"downloads from"| PyDist
    LockM -->|"creates env via"| VirtualEnv
    LockM -->|"resolves deps via"| PipTools
    SyncM -->|"resolves deps via"| PipTools
    BuildM -->|"wraps"| BuildTool
    PublishM -->|"wraps"| Twine
    LintFmt -->|"wraps"| Ruff
    ShimTUI -->|"generates"| FileSys["File System"]:::external
    Template -->|"writes scaffold to"| FileSys
    PyProj -->|"manages pyproject.toml"| FileSys

    Devtools -.->|"helper scripts"| Repo
    CI -->|"deploy docs"| Docs
    CI -->|"tests & lint"| Repo

    %% Click Events
    click CLIParser "https://github.com/astral-sh/rye/tree/main/rye/src/cli"
    click Config "https://github.com/astral-sh/rye/blob/main/rye/src/config.rs"
    click Installer "https://github.com/astral-sh/rye/blob/main/rye/src/installer.rs"
    click LockM "https://github.com/astral-sh/rye/blob/main/rye/src/lock.rs"
    click SyncM "https://github.com/astral-sh/rye/blob/main/rye/src/sync.rs"
    click BuildM "https://github.com/astral-sh/rye/blob/main/rye/src/cli/build.rs"
    click PublishM "https://github.com/astral-sh/rye/blob/main/rye/src/cli/publish.rs"
    click LintFmt "https://github.com/astral-sh/rye/blob/main/rye/src/cli/fmt.rs"
    click Ruff "https://github.com/astral-sh/rye/blob/main/rye/src/utils/ruff.rs"
    click PyProj "https://github.com/astral-sh/rye/blob/main/rye/src/pyproject.rs"
    click Sources "https://github.com/astral-sh/rye/tree/main/rye/src/sources"
    click Template "https://github.com/astral-sh/rye/tree/main/rye/src/templates"
    click ShimTUI "https://github.com/astral-sh/rye/blob/main/rye/src/cli/shim.rs"
    click Devtools "https://github.com/astral-sh/rye/tree/main/rye-devtools"
    click Docs "https://github.com/astral-sh/rye/tree/main/docs"
    click CI "https://github.com/astral-sh/rye/tree/main/.github/workflows"

    %% Styles
    classDef cli fill:#cce5ff,stroke:#004085,color:#004085
    classDef core fill:#d1ecf1,stroke:#0c5460,color:#0c5460
    classDef adapter fill:#d4edda,stroke:#155724,color:#155724
    classDef devtools fill:#f8f9fa,stroke:#6c757d,color:#6c757d,stroke-dasharray: 5 5
    classDef docs fill:#f8f9fa,stroke:#6c757d,color:#6c757d
    classDef cicd fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef external fill:#fff3cd,stroke:#856404,color:#856404
```
