# paiml/depyler architecture

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

- Interactive diagram: https://gitdiagram.com/paiml/depyler
- Repository: https://github.com/paiml/depyler

## Overview

##### Project type and purpose
- Depyler is an open-source, Rust-based Python-to-Rust transpiler tool and library with CLI, HTTP server, LSP server, formal verification, energy-efficiency optimizations, and a web-based playground. It consists of multiple Cargo crates for core functionality, analysis, verification, Ruchy target, WASM packaging, CLI, and an interactive TypeScript/React front-end.

##### File structure
- Top-level workspace (Cargo.toml) with sub-crates under `crates/`:
- depyler-core: pipeline (AST→HIR→optimizer→codegen)
- depyler-analyzer: complexity metrics
- depyler-verify: contract & memory safety checks
- depyler-mcp: Model Context Protocol server/transport
- depyler-ruchy: Ruchy script target
- depyler-wasm: WASM bindings for browser usage
- depyler-quality: CLI commands around quality checks
- depyler (top-level crate): CLI entrypoint and multi-mode server (HTTP, LSP, interactive)
- A `playground/` directory holds a TypeScript/React web app, WASM runner, Deno tasks, Docker compose, Nginx config.
- CI/CD workflows in `.github/workflows/`, release scripts in `scripts/`, benchmarking in `benches/`, integration tests under `tests/`.

##### README for additional insights
- Multi-target support (Rust, Ruchy, WASM)
- CLI, HTTP server, LSP server, MCP server modes
- Emphasis on testing (property, mutation, fuzzing), profiling, documentation generation

##### Detail & granularity
- Crate or logical service as its own component
- Versioning or environment details (e.g., Docker container, node/Deno)
- Don’t omit the playground – show how the WASM module interacts with the core
- Optionally, add an inset for the CI/CD pipeline showing build → test → release

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Front-ends (orange)
    subgraph "Front-ends"
        direction TB
        CLI["depyler CLI/Server\n(crates/depyler)"]:::frontend
        HTTP["HTTP API\n(sub-command)"]:::frontend
        LSP["LSP Server\n(sub-command)"]:::frontend
    end

    %% Core Pipeline (blue)
    subgraph "Core Pipeline" 
        direction TB
        CoreLib["Pipeline Core\n(crates/depyler-core)"]:::core
        Parser["Python Parser\n(rustpython AST)"]:::core
        HIR["HIR Transformer"]:::core
        Checker["Type Inference &\nBorrow Checker"]:::core
        Opt["Optimizations"]:::core
        CodeGen["Code Generator\n(syn Rust AST)"]:::core
    end

    %% Extensions (green)
    subgraph "Extension Crates"
        direction TB
        Analyzer["Analyzer\n(crates/depyler-analyzer)"]:::ext
        Verifier["Verifier\n(crates/depyler-verify)"]:::ext
        RuchyExt["Ruchy Target\n(crates/depyler-ruchy)"]:::ext
        WASMExt["WASM Binding\n(crates/depyler-wasm)"]:::ext
        MCPExt["MCP Integration\n(crates/depyler-mcp)"]:::ext
    end

    %% Outputs (cylinders)
    rustc["rustc Compiler"]:::db
    ruchyInt["Ruchy Interpreter"]:::db
    wasmRun["WASM Runtime"]:::db

    %% Playground (orange)
    subgraph "Web Playground"
        direction TB
        UI["Playground UI\n(playground/src/)"]:::frontend
        WASMRunner["WASM Runner\n(playground/depyler-playground)"]:::ext
        ExecutionMgr["Execution Manager"]:::core
    end

    %% CI/CD & Deployment (gray)
    subgraph "CI/CD & Deployment"
        direction TB
        CI["GitHub Actions\n(.github/workflows/)"]:::infra
        Scripts["Release & Quality Scripts\n(scripts/)"]:::infra
        Bench["Benchmarks\n(benches/)"]:::infra
        Tests["Integration Tests\n(tests/)"]:::infra
        Docker["Docker & Nginx\n(playground/Dockerfile,\nplayground/docker-compose.yml,\nplayground/nginx.conf)"]:::infra
    end

    %% Connections
    CLI -->|"invoke"| CoreLib
    HTTP -->|"HTTP request"| CoreLib
    LSP -->|"LSP request"| CoreLib

    CoreLib --> Parser
    Parser --> HIR
    HIR --> Checker
    Checker --> Opt
    Opt --> CodeGen

    CodeGen -->|"emit Rust code"| rustc
    CodeGen -->|"emit Ruchy script"| ruchyInt
    CodeGen -->|"emit WASM module"| wasmRun

    CoreLib -->|"- Analyzer hook"| Analyzer
    CoreLib -->|"- Verification hook"| Verifier
    CoreLib -->|"- Ruchy target hook"| RuchyExt
    CoreLib -->|"- WASM binding hook"| WASMExt
    CoreLib -->|"- MCP transport hook"| MCPExt

    UI -->|"WASM messages"| WASMRunner
    WASMRunner -->|"execute via depyler-wasm"| wasmRun
    WASMRunner -->|"call Execution Manager"| ExecutionMgr
    UI -->|"HTTP/MCP calls"| HTTP
    UI -->|"MCP calls"| MCPExt

    CI --> CI
    CI --> Scripts
    CI --> Bench
    CI --> Tests
    CI --> Docker

    %% Click Events
    click CLI "https://github.com/paiml/depyler/blob/main/crates/depyler/src/main.rs"
    click CLI "https://github.com/paiml/depyler/blob/main/crates/depyler/src/lib.rs"
    click CoreLib "https://github.com/paiml/depyler/blob/main/crates/depyler-core/src/lib.rs"
    click Analyzer "https://github.com/paiml/depyler/blob/main/crates/depyler-analyzer/src/lib.rs"
    click Verifier "https://github.com/paiml/depyler/blob/main/crates/depyler-verify/src/lib.rs"
    click RuchyExt "https://github.com/paiml/depyler/blob/main/crates/depyler-ruchy/src/lib.rs"
    click WASMExt "https://github.com/paiml/depyler/blob/main/crates/depyler-wasm/src/lib.rs"
    click MCPExt "https://github.com/paiml/depyler/blob/main/crates/depyler-mcp/src/lib.rs"
    click UI "https://github.com/paiml/depyler/tree/main/playground/src/"
    click WASMRunner "https://github.com/paiml/depyler/blob/main/playground/depyler-playground/src/lib.rs"
    click Docker "https://github.com/paiml/depyler/tree/main/playground/Dockerfile"
    click Docker "https://github.com/paiml/depyler/blob/main/playground/docker-compose.yml"
    click Docker "https://github.com/paiml/depyler/blob/main/playground/nginx.conf"
    click CI "https://github.com/paiml/depyler/blob/main/ .github/workflows/ci.yml"
    click CI "https://github.com/paiml/depyler/blob/main/ .github/workflows/release.yml"
    click CI "https://github.com/paiml/depyler/blob/main/ .github/workflows/quality-gates.yml"
    click Scripts "https://github.com/paiml/depyler/blob/main/scripts/prepare-release.sh"
    click Scripts "https://github.com/paiml/depyler/blob/main/scripts/publish-crates.sh"
    click Scripts "https://github.com/paiml/depyler/blob/main/scripts/quality-check.sh"
    click Bench "https://github.com/paiml/depyler/blob/main/benches/transpilation.rs"
    click Bench "https://github.com/paiml/depyler/blob/main/benches/binary_size.rs"
    click Bench "https://github.com/paiml/depyler/blob/main/benches/memory_usage.rs"
    click Tests "https://github.com/paiml/depyler/blob/main/tests/integration/transpilation_tests.rs"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,color:#004085;
    classDef ext fill:#d4edda,stroke:#155724,color:#155724;
    classDef frontend fill:#ffeeba,stroke:#856404,color:#856404;
    classDef infra fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef db fill:#f5c6cb,stroke:#721c24,color:#721c24;
```
