# codegen-sh/pink architecture

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

- Interactive diagram: https://gitdiagram.com/codegen-sh/pink
- Repository: https://github.com/codegen-sh/pink

## Overview

##### Project type and purpose
- This is an open-source, multi-crate Rust library and CLI tool (“Pink”) that implements a multi-lingual type analysis and refactoring engine.
- It provides build-time code generators (CST, AST, Python bindings) and run-time components (core SDK, incremental analyzer, CLI, Python FFI).

##### File structure
- Top-level crates:
– codegen-sdk-common, codegen-sdk-cst, codegen-sdk-ast, codegen-sdk-resolution
– codegen-sdk-cst-generator, codegen-sdk-ast-generator, codegen-bindings-generator
– codegen-sdk-analyzer
– languages/* (one crate per target language)
– bindings/python (Python FFI)
– src/main.rs (Pink CLI binary)
- Configuration and tooling:
– Cargo.toml, rust-toolchain, CI workflows, Insta snapshot tests, Netlify docs.

##### Extract architectural insights from the README
- Core pattern: modular monorepo with separation of concerns by crate.
- Build-time pipeline: generate CST → generate AST/queries → generate language bindings → compile language crates.
- Run-time pipeline: CLI or Python binding loads parsed caches → uses analyzer for incremental computation.

##### Main components
a. Build-time code generators (three crates)
- codegen-sdk-cst-generator
- codegen-sdk-ast-generator
- codegen-bindings-generator
b. Core library crates (Rust)
- codegen-sdk-common
- codegen-sdk-cst
- codegen-sdk-ast
- codegen-sdk-resolution
c. Language-specific crates
- languages/codegen-sdk-* (go, java, typescript, etc.)
d. Run-time engine
- codegen-sdk-analyzer
- Pink CLI (src/main.rs)
- Python binding (bindings/python)
e. External tools and services
- Cargo build, GitHub Actions CI, Insta snapshot testing

##### Relationships and interactions
- codegen-sdk-common feeds into cst, ast, resolution crates.
- codegen-sdk-cst and common feed into ast generator and ast crate.
- codegen-sdk-resolution uses ast and common.
- language crates depend on common + generated AST/CST.
- analyzer depends on all core crates.
- CLI binary uses analyzer and core crates.
- Python binding wraps core crates via FFI and exposes a Python API.

##### Architectural patterns and design principles
- Modular crate-per-responsibility design for isolation, parallel compilation, and testability.
- Build-time code generation pipeline decoupled from run-time analysis engine.
- Incremental re-computation pattern in codegen-sdk-analyzer for performance.
- FFI boundary between Rust core and Python.

- Clear labels (crate names, generator names, binary names)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build-time Code Generators
    subgraph "Build-time Code Generators"
        direction TB
        cstGen["codegen-sdk-cst-generator"]:::generator
        astGen["codegen-sdk-ast-generator"]:::generator
        bindingsGen["codegen-bindings-generator"]:::generator
    end

    %% Core Libraries
    subgraph "Core Libraries"
        direction TB
        common["codegen-sdk-common"]:::core
        cst["codegen-sdk-cst"]:::core
        ast["codegen-sdk-ast"]:::core
        resolution["codegen-sdk-resolution"]:::core
    end

    %% Language Extensions
    subgraph "Language Extensions"
        direction TB
        goExt["Go SDK"]:::language
        javaExt["Java SDK"]:::language
        jsonExt["JSON SDK"]:::language
        mdExt["Markdown SDK"]:::language
        pyExt["Python SDK"]:::language
        rubyExt["Ruby SDK"]:::language
        rustExt["Rust SDK"]:::language
        tomlExt["TOML SDK"]:::language
        tsQueryExt["TS Query SDK"]:::language
        tsExt["TypeScript SDK"]:::language
        yamlExt["YAML SDK"]:::language
    end

    %% Run-time Interfaces
    subgraph "Run-time Interfaces"
        direction TB
        analyzer["codegen-sdk-analyzer"]:::runtime
        cli["Pink CLI"]:::runtime
        pythonFFI["Python FFI Binding"]:::runtime
    end

    %% External Tools
    subgraph "External Tools"
        direction TB
        cargo["Cargo Build"]:::external
        ci["GitHub Actions CI"]:::external
    end

    %% Dependencies: Generators to Core
    cstGen -->|generates| cst
    astGen -->|generates| ast
    bindingsGen -->|generates| goExt
    bindingsGen -->|generates| javaExt
    bindingsGen -->|generates| jsonExt
    bindingsGen -->|generates| mdExt
    bindingsGen -->|generates| pyExt
    bindingsGen -->|generates| rubyExt
    bindingsGen -->|generates| rustExt
    bindingsGen -->|generates| tomlExt
    bindingsGen -->|generates| tsQueryExt
    bindingsGen -->|generates| tsExt
    bindingsGen -->|generates| yamlExt

    %% Core Library dependencies
    common --> cst
    common --> ast
    common --> resolution
    cst --> astGen
    common --> astGen
    cst --> ast
    astGen --> ast
    ast --> resolution
    common --> resolution

    %% Language Extensions depend on core
    common --> goExt
    cst --> goExt
    ast --> goExt
    common --> javaExt
    cst --> javaExt
    ast --> javaExt
    common --> jsonExt
    cst --> jsonExt
    ast --> jsonExt
    common --> mdExt
    cst --> mdExt
    ast --> mdExt
    common --> pyExt
    cst --> pyExt
    ast --> pyExt
    common --> rubyExt
    cst --> rubyExt
    ast --> rubyExt
    common --> rustExt
    cst --> rustExt
    ast --> rustExt
    common --> tomlExt
    cst --> tomlExt
    ast --> tomlExt
    common --> tsQueryExt
    cst --> tsQueryExt
    ast --> tsQueryExt
    common --> tsExt
    cst --> tsExt
    ast --> tsExt
    common --> yamlExt
    cst --> yamlExt
    ast --> yamlExt

    %% Run-time dependencies
    common --> analyzer
    cst --> analyzer
    ast --> analyzer
    resolution --> analyzer
    analyzer --> cli
    analyzer --> pythonFFI

    %% External triggers
    cargo --> cstGen
    cargo --> astGen
    cargo --> bindingsGen
    cargo --> common
    cargo --> analyzer
    ci --> cargo

    %% Click Events
    click cstGen "https://github.com/codegen-sh/pink/tree/main/codegen-sdk-cst-generator/"
    click astGen "https://github.com/codegen-sh/pink/tree/main/codegen-sdk-ast-generator/"
    click bindingsGen "https://github.com/codegen-sh/pink/tree/main/codegen-bindings-generator/"
    click common "https://github.com/codegen-sh/pink/tree/main/codegen-sdk-common/"
    click cst "https://github.com/codegen-sh/pink/tree/main/codegen-sdk-cst/"
    click ast "https://github.com/codegen-sh/pink/tree/main/codegen-sdk-ast/"
    click resolution "https://github.com/codegen-sh/pink/tree/main/codegen-sdk-resolution/"
    click analyzer "https://github.com/codegen-sh/pink/tree/main/codegen-sdk-analyzer/"
    click cli "https://github.com/codegen-sh/pink/blob/main/src/main.rs"
    click pythonFFI "https://github.com/codegen-sh/pink/tree/main/bindings/python/"
    click goExt "https://github.com/codegen-sh/pink/tree/main/languages/codegen-sdk-go/"
    click javaExt "https://github.com/codegen-sh/pink/tree/main/languages/codegen-sdk-java/"
    click jsonExt "https://github.com/codegen-sh/pink/tree/main/languages/codegen-sdk-json/"
    click mdExt "https://github.com/codegen-sh/pink/tree/main/languages/codegen-sdk-markdown/"
    click pyExt "https://github.com/codegen-sh/pink/tree/main/languages/codegen-sdk-python/"
    click rubyExt "https://github.com/codegen-sh/pink/tree/main/languages/codegen-sdk-ruby/"
    click rustExt "https://github.com/codegen-sh/pink/tree/main/languages/codegen-sdk-rust/"
    click tomlExt "https://github.com/codegen-sh/pink/tree/main/languages/codegen-sdk-toml/"
    click tsQueryExt "https://github.com/codegen-sh/pink/tree/main/languages/codegen-sdk-ts-query/"
    click tsExt "https://github.com/codegen-sh/pink/tree/main/languages/codegen-sdk-typescript/"
    click yamlExt "https://github.com/codegen-sh/pink/tree/main/languages/codegen-sdk-yaml/"

    %% Styles
    classDef generator fill:#f9a825,stroke:#c17900,color:#000;
    classDef core fill:#2196f3,stroke:#1769aa,color:#fff;
    classDef language fill:#4caf50,stroke:#357a38,color:#fff;
    classDef runtime fill:#9c27b0,stroke:#6d1b7b,color:#fff;
    classDef external fill:#90a4ae,stroke:#607d8b,color:#000;
```
