# staplerio/carbon-lang_compiler architecture

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

- Interactive diagram: https://gitdiagram.com/staplerio/carbon-lang_compiler
- Repository: https://github.com/staplerio/carbon-lang_compiler

## Overview

##### Project type and purpose
- This is a multi‑crate Rust workspace implementing the Carbon programming language compiler plus a CLI front‑end and a small math library.
- Purpose: parse Carbon source files, build an AST, perform optimizations/type checks, generate target packages (assembly or bytecode), and provide a CLI tool (`arc`) to orchestrate compilation.

##### File structure
- Top‑level crates:
- executables/arc – command‑line tool
- libraries/compiler – core compiler library
- libraries/apa – auxiliary arithmetic library
- Within the compiler crate, you see four logical subsystems (as per README):
- lexer/ – tokenization rules & tokenizer
- parser/ – AST construction & parsing pipeline
- optimizer – (implied within package_generator/type_inference)
- package_generator/ – transforms IR into final package
- Shared modules under compiler/src/shared hold AST definitions, tokens, errors, utilities, and common package‑generation data structures.
- Tests are co‑located under each subsystem to validate functionality.

##### README for additional insights
- Confirms four compiler phases: Lexer → Parser → Optimizer → Package generator.

##### Detail without over‑splitting
- Compiler phase as its own component but avoid drilling down into every single Rust file.
- Only the critical sub‑modules that define major behaviors (e.g., lex_rules in Lexer, builder/blocks in Parser, command_builder in Package Generator).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Main Flow
    Source["Source File"]:::external
    CLI["arc CLI\n(Rust/Cargo binary)"]:::cli
    LEXER["Lexer"]:::lexer
    PARSER["Parser"]:::parser
    OPT["Optimizer\n/Type Inference"]:::optimizer
    GEN["Package Generator"]:::generator
    Output["Generated Package\n(assembly/object/bytecode)"]:::external

    Source -->|input| CLI
    CLI -->|invokes| LEXER
    LEXER -->|TokenStream| PARSER
    PARSER -->|AST<Node>| OPT
    OPT -->|TypedIR| GEN
    GEN -->|PackageDescriptor| Output

    %% Shared Modules
    Shared["Shared Modules"]:::shared
    Shared -.->|uses| LEXER
    Shared -.->|uses| PARSER
    Shared -.->|uses| OPT
    Shared -.->|uses| GEN

    %% Math Library
    APA["apa Math Library"]:::external
    APA -.->|math utils| OPT

    %% Submodules for CLI
    subgraph "arc CLI Submodules"
        direction TB
        Main["main.rs"]:::cli
        Commands["commands"]:::cli
        Managers["managers"]:::cli
        Models["models"]:::cli
    end
    CLI --> Main

    %% Submodules for Lexer
    subgraph "Lexer Submodules"
        direction TB
        LexMod["mod.rs"]:::lexer
        Tokenize["tokenize.rs"]:::lexer
        LexRules["lex_rules"]:::lexer
    end
    LEXER --> LexMod
    LEXER --> Tokenize
    LEXER --> LexRules

    %% Submodules for Parser
    subgraph "Parser Submodules"
        direction TB
        ParserMod["mod.rs"]:::parser
        Pipeline["pipeline.rs"]:::parser
        Decorator["decorator.rs"]:::parser
        Builder["builder"]:::parser
    end
    PARSER --> ParserMod
    PARSER --> Pipeline
    PARSER --> Decorator
    PARSER --> Builder

    %% Submodules for Optimizer
    subgraph "Optimizer Submodules"
        direction TB
        TI_MOD["type_inference/mod.rs"]:::optimizer
        Expr["expression.rs"]:::optimizer
    end
    OPT --> TI_MOD
    OPT --> Expr

    %% Submodules for Package Generator
    subgraph "PackageGen Submodules"
        direction TB
        PGMod["mod.rs"]:::generator
        AvailCheck["availability_check"]:::generator
        CmdBuilder["command_builder"]:::generator
        UtilsPG["utils.rs"]:::generator
        LATree["linear_action_tree_adapter.rs"]:::generator
    end
    GEN --> PGMod
    GEN --> AvailCheck
    GEN --> CmdBuilder
    GEN --> UtilsPG
    GEN --> LATree

    %% Submodules for Shared
    subgraph "Shared Submodules"
        direction TB
        AST["ast"]:::shared
        TokenMod["token"]:::shared
        ErrorMod["error"]:::shared
        PGShared["package_generation"]:::shared
        UtilsShared["utils"]:::shared
    end
    Shared --> AST
    Shared --> TokenMod
    Shared --> ErrorMod
    Shared --> PGShared
    Shared --> UtilsShared

    %% Click Events for CLI
    click Main "https://github.com/staplerio/carbon-lang_compiler/blob/master/executables/arc/src/main.rs"
    click Commands "https://github.com/staplerio/carbon-lang_compiler/tree/master/executables/arc/src/commands"
    click Managers "https://github.com/staplerio/carbon-lang_compiler/tree/master/executables/arc/src/managers"
    click Models "https://github.com/staplerio/carbon-lang_compiler/tree/master/executables/arc/src/models"

    %% Click Events for Compiler Library
    click LEXER "https://github.com/staplerio/carbon-lang_compiler/blob/master/libraries/compiler/src/lexer/mod.rs"
    click LexMod "https://github.com/staplerio/carbon-lang_compiler/blob/master/libraries/compiler/src/lexer/mod.rs"
    click Tokenize "https://github.com/staplerio/carbon-lang_compiler/blob/master/libraries/compiler/src/lexer/tokenize.rs"
    click LexRules "https://github.com/staplerio/carbon-lang_compiler/tree/master/libraries/compiler/src/lexer/lex_rules"
    click PARSER "https://github.com/staplerio/carbon-lang_compiler/blob/master/libraries/compiler/src/parser/mod.rs"
    click ParserMod "https://github.com/staplerio/carbon-lang_compiler/blob/master/libraries/compiler/src/parser/mod.rs"
    click Pipeline "https://github.com/staplerio/carbon-lang_compiler/blob/master/libraries/compiler/src/parser/pipeline.rs"
    click Decorator "https://github.com/staplerio/carbon-lang_compiler/blob/master/libraries/compiler/src/parser/decorator.rs"
    click Builder "https://github.com/staplerio/carbon-lang_compiler/tree/master/libraries/compiler/src/parser/builder"
    click TI_MOD "https://github.com/staplerio/carbon-lang_compiler/blob/master/libraries/compiler/src/package_generator/type_inference/mod.rs"
    click Expr "https://github.com/staplerio/carbon-lang_compiler/blob/master/libraries/compiler/src/package_generator/type_inference/expression.rs"
    click GEN "https://github.com/staplerio/carbon-lang_compiler/blob/master/libraries/compiler/src/package_generator/mod.rs"
    click AvailCheck "https://github.com/staplerio/carbon-lang_compiler/tree/master/libraries/compiler/src/package_generator/availability_check"
    click CmdBuilder "https://github.com/staplerio/carbon-lang_compiler/tree/master/libraries/compiler/src/package_generator/command_builder"
    click UtilsPG "https://github.com/staplerio/carbon-lang_compiler/blob/master/libraries/compiler/src/package_generator/utils.rs"
    click LATree "https://github.com/staplerio/carbon-lang_compiler/blob/master/libraries/compiler/src/package_generator/linear_action_tree_adapter.rs"
    click Shared "https://github.com/staplerio/carbon-lang_compiler/tree/master/libraries/compiler/src/shared"
    click AST "https://github.com/staplerio/carbon-lang_compiler/tree/master/libraries/compiler/src/shared/ast"
    click TokenMod "https://github.com/staplerio/carbon-lang_compiler/tree/master/libraries/compiler/src/shared/token"
    click ErrorMod "https://github.com/staplerio/carbon-lang_compiler/tree/master/libraries/compiler/src/shared/error"
    click PGShared "https://github.com/staplerio/carbon-lang_compiler/tree/master/libraries/compiler/src/shared/package_generation"
    click UtilsShared "https://github.com/staplerio/carbon-lang_compiler/tree/master/libraries/compiler/src/shared/utils"
    click APA "https://github.com/staplerio/carbon-lang_compiler/blob/master/libraries/apa/src/lib.rs"
    click APA "https://github.com/staplerio/carbon-lang_compiler/tree/master/libraries/apa/src/apa"
    click APA "https://github.com/staplerio/carbon-lang_compiler/blob/master/libraries/apa/src/models/math_object.rs"
    click APA "https://github.com/staplerio/carbon-lang_compiler/blob/master/libraries/apa/src/apa/utils.rs"

    classDef cli fill:#f9f,stroke:#333,stroke-width:1px
    classDef lexer fill:#cfc,stroke:#333,stroke-width:1px
    classDef parser fill:#ccf,stroke:#333,stroke-width:1px
    classDef optimizer fill:#fc9,stroke:#333,stroke-width:1px
    classDef generator fill:#c9f,stroke:#333,stroke-width:1px
    classDef shared fill:#eee,stroke:#333,stroke-width:1px
    classDef external fill:#ffe,stroke:#333,stroke-width:1px
```
