# guilhermesob/minilang-compiler architecture

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

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

## Overview

##### Project Type and Purpose
- This is a single-crate compiler for the educational “MiniLang” language, implemented entirely in Rust.
- Its main goal is to read MiniLang source code, perform lexical and syntactic analysis, build an AST (Abstract Syntax Tree), and prepare for further stages such as optimization or code generation.

##### File Structure Analysis
- Top-level directory “Compillers/mini_lang_compiler” contains:
- Cargo.toml – project metadata and dependencies
- src/lib.rs – core compiler modules and library API
- src/main.rs – CLI entry point that wires together the compiler pipeline
- No separate frontend/backend directories; the compiler pipeline is implemented as a sequence of modules within one crate.

##### Key Architecture Insights from README
- Pipeline stages:
1. Lexical Analysis (tokenization)
2. Syntactic Analysis (parsing into AST)
3. AST representation for potential optimization or code generation
- Supported language features: arithmetic expressions, parentheses, identifiers, comparisons, logical operators.
- Uses Rust and Cargo; tests are invoked via `cargo test`.

##### Main Components
a. CLI / Frontend
- main.rs parses command-line arguments, reads source files, invokes the compiler library.
b. Lexer Module
- Converts raw source text → token stream.
c. Parser Module
- Consumes tokens → builds AST data structures.
d. AST Data Model
- In-memory representation of program structure.
e. (Future) Code Generator / Backend
- Would traverse AST → emit target code or IR.
f. Testing Harness
- test modules invoked by Cargo for unit tests of each compiler stage.
g. External Crates
- Any third-party Rust libraries listed in Cargo.toml (e.g., clap for CLI, anyhow for error handling).

##### Relationships and Data Flow
- Source Code file → CLI
→ Lexer → Token Stream
→ Parser → AST
→ (Optional) Semantic Analyzer/Optimizer → Code Generator → Output (binary or IR)

##### Architectural Patterns and Principles
- Pipeline Pattern: each compiler stage is a separate module with clear input/output contracts.
- Separation of Concerns: CLI (IO) vs. pure library logic (lexing/parsing).
- Modularity: each stage can be tested independently.

##### Technologies / Frameworks
- Rust (language) / Cargo (build & dependency management).
- Standard Rust crates for error handling, CLI parsing, and testing.

##### Final Advice
- Be exhaustive: include even simple modules like tests and Cargo configuration.
- Avoid over-complicating: show a straight pipeline, then annotate hooks or extension points.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% I/O Layer
    subgraph "I/O Layer"
        direction TB
        Source["Source Code (.*\\.ml)"]:::io
        CLI["CLI – main.rs"]:::io
    end

    %% Core Pipeline Modules
    subgraph "Compiler Pipeline"
        direction TB
        Lexer["Lexer Module"]:::core
        Parser["Parser Module"]:::core
        AST["AST Data Model"]:::core
        CodeGen["Code Generator (future)"]:::core
    end

    %% Output Artifact
    Output[(Binary / IR)]:::io

    %% Testing Harness
    subgraph "Testing Harness"
        direction TB
        Tests["Unit Tests"]:::test
    end

    %% External Dependencies & CI
    subgraph "External & CI"
        direction TB
        Cargo["Cargo.toml"]:::external
        CI["CI Workflow"]:::external
    end

    %% Data Flow
    Source -->|reads| CLI
    CLI -->|invokes| Lexer
    Lexer -->|tokens| Parser
    Parser -->|AST| AST
    AST -->|feed| CodeGen
    CodeGen -->|emit| Output

    %% Testing Hooks
    Tests -.->|tests lexer| Lexer
    Tests -.->|tests parser| Parser
    Tests -.->|tests AST| AST

    %% External relations
    CLI -->|uses| Cargo
    Lexer -->|depends on| Cargo
    Parser -->|depends on| Cargo
    AST -->|depends on| Cargo
    Tests -->|via Cargo test| Cargo
    CI -->|runs| Cargo

    %% Click Events
    click CLI "https://github.com/guilhermesob/minilang-compiler/blob/main/Compillers/mini_lang_compiler/src/main.rs"
    click Lexer "https://github.com/guilhermesob/minilang-compiler/blob/main/Compillers/mini_lang_compiler/src/lib.rs"
    click Parser "https://github.com/guilhermesob/minilang-compiler/blob/main/Compillers/mini_lang_compiler/src/lib.rs"
    click AST "https://github.com/guilhermesob/minilang-compiler/blob/main/Compillers/mini_lang_compiler/src/lib.rs"
    click Tests "https://github.com/guilhermesob/minilang-compiler/blob/main/Compillers/mini_lang_compiler/src/lib.rs"
    click Cargo "https://github.com/guilhermesob/minilang-compiler/blob/main/Compillers/mini_lang_compiler/Cargo.toml"
    click CI "https://github.com/guilhermesob/minilang-compiler/blob/main/.github/workflows/rust.yml"

    %% Styles
    classDef io fill:#c8e6c9,stroke:#2e7d32,color:#1b5e20;
    classDef core fill:#bbdefb,stroke:#0d47a1,color:#0d47a1;
    classDef external fill:#ffe0b2,stroke:#ef6c00,color:#e65100;
    classDef test fill:#ffe0b2,stroke-dasharray: 5 5,stroke:#ef6c00,color:#e65100;
```
