# saulvaldelvira/compiler architecture

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

- Interactive diagram: https://gitdiagram.com/saulvaldelvira/compiler
- Repository: https://github.com/saulvaldelvira/compiler

## Overview

##### Main Components
- Compiler Driver (bin/compiler): This is the main executable that initializes the compilation process.
- Lexical Analysis: Represented by lib/lexer – handles tokenizing the source input.
- Parsing: Represented by lib/parser – converts the stream of tokens into a concrete AST (abstract syntax tree).
- AST Representation: Found in lib/ast – defines the syntax structures with declarations, expressions, statements, types, etc.
- AST Lowering: In lib/ast_lowering – performs transformations or lowering from the high-level AST into a simpler or more canonical form.
- AST Validation: In lib/ast_validate – ensures the correctness of the AST.
- Semantic Analysis: In lib/semantic – applies semantic rules, type checking, and other analyses on the AST.
- Intermediate Representations:
- High-Level IR (HIR): Implemented in lib/hir and complemented by lib/hir_passes and lib/hir_typecheck.
- (There might also be interactions with lib/session and lib/span for session management and source code spans.)
- Code Generation: In lib/mapl_codegen – translates the IR or lowered structures into target code or MIR.
- Supporting Libraries:
- lib/arena for memory allocation patterns (likely used by various phases).
- lib/error_manager to centralize error reporting.
- lib/compiler_driver, which might wrap and coordinate the entire compilation process.

##### Relationships and Data Flow
- The Compiler Driver receives the source file and initiates the process.
- The Lexical Analyzer (lexer) processes the raw source into a stream of tokens.
- The Parser uses the token stream to build the AST.
- AST Lowering and AST Validation work on the AST to prepare and check it before semantic analysis.
- Semantic Analysis then validates type rules and semantics, possibly producing errors that are coordinated by the Error Manager.
- The semantic phase passes results to the HIR phase, where the qualified representations are built (in lib/hir), then processed further by HIR passes and type checking.
- Finally, the Code Generator (mapl_codegen) translates the IR into code, likely using helper modules for addressing, metadata, and evaluation (indicated by the structure inside the code generation library).

##### Architectural Patterns and Design Principles
- Modularity: Each phase of the compiler is separated as a different crate, which clearly models the pipeline.
- Layered Architecture: Data flows from the lexer to the parser, then to the AST, followed by semantic analysis, IR/HIR, and finally code generation.
- Error Handling and Cross-Cutting Concerns: Components such as the Error Manager, Session, and Span libraries add cross-phase support.
- The use of a driver library shows that the orchestration is separated from the concerns of each compilation phase.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input
    A["Source Code"]:::input

    %% Compiler Driver
    B["Compiler Driver"]:::corePhase

    %% Frontend Phase: Lexical Analysis, Parsing, AST
    subgraph "Frontend"
        C["Lexical Analysis"]:::corePhase
        D["Parsing"]:::corePhase
        E["AST Representation"]:::corePhase
    end

    %% AST Processing Phase: AST Lowering and AST Validation
    subgraph "AST Processing"
        F["AST Lowering"]:::corePhase
        G["AST Validation"]:::corePhase
    end

    %% Semantic Analysis
    H["Semantic Analysis"]:::corePhase

    %% High-Level Intermediate Representation (HIR)
    subgraph "HIR"
        I["HIR Definition"]:::corePhase
        J["HIR Passes"]:::corePhase
        K["HIR Type Checking"]:::corePhase
    end

    %% Code Generation
    L["Code Generation"]:::corePhase

    %% Supporting Modules
    subgraph "Supporting Modules"
        M["Memory Arena"]:::support
        N["Error Management"]:::support
        O["Compiler Coordination"]:::support
        P["Session Management"]:::support
        Q["Source Code Spans"]:::support
    end

    %% Main Flow
    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
    F --> G
    G --> H
    H --> I
    I --> J
    J --> K
    K --> L

    %% Error flow from phases to Error Management
    C ---|"errors"| N
    D ---|"errors"| N
    E ---|"errors"| N
    F ---|"errors"| N
    G ---|"errors"| N
    H ---|"errors"| N
    I ---|"errors"| N
    J ---|"errors"| N
    K ---|"errors"| N
    L ---|"errors"| N

    %% Interaction between Compiler Driver and Compiler Coordination
    B --- O

    %% Supporting modules linked to Code Generation
    M --- L
    P --- L
    Q --- L

    %% Click Events
    click B "https://github.com/saulvaldelvira/compiler/blob/master/bin/compiler/src/main.rs"
    click C "https://github.com/saulvaldelvira/compiler/tree/master/lib/lexer"
    click D "https://github.com/saulvaldelvira/compiler/blob/master/lib/parser/src/lib.rs"
    click E "https://github.com/saulvaldelvira/compiler/blob/master/lib/ast/src/lib.rs"
    click F "https://github.com/saulvaldelvira/compiler/blob/master/lib/ast_lowering/src/lib.rs"
    click G "https://github.com/saulvaldelvira/compiler/blob/master/lib/ast_validate/src/lib.rs"
    click H "https://github.com/saulvaldelvira/compiler/blob/master/lib/semantic/src/lib.rs"
    click I "https://github.com/saulvaldelvira/compiler/blob/master/lib/hir/src/lib.rs"
    click J "https://github.com/saulvaldelvira/compiler/blob/master/lib/hir_passes/src/lib.rs"
    click K "https://github.com/saulvaldelvira/compiler/blob/master/lib/hir_typecheck/src/lib.rs"
    click L "https://github.com/saulvaldelvira/compiler/blob/master/lib/mapl_codegen/src/lib.rs"
    click M "https://github.com/saulvaldelvira/compiler/blob/master/lib/arena/src/lib.rs"
    click N "https://github.com/saulvaldelvira/compiler/blob/master/lib/error_manager/src/lib.rs"
    click O "https://github.com/saulvaldelvira/compiler/blob/master/lib/compiler_driver/src/lib.rs"
    click P "https://github.com/saulvaldelvira/compiler/blob/master/lib/session/src/lib.rs"
    click Q "https://github.com/saulvaldelvira/compiler/blob/master/lib/span/src/lib.rs"

    %% Class definitions for colors
    classDef input fill:#ffe082,stroke:#ff6f00,stroke-width:2px;
    classDef corePhase fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;
    classDef support fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;
```
