# rubenjr0/elk architecture

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

- Interactive diagram: https://gitdiagram.com/rubenjr0/elk
- Repository: https://github.com/rubenjr0/elk

## Overview

##### Main Components
- Compiler Core (“compiler-core”):
– Contains the central compilation logic.
– Has a clearly delineated “frontend” module, which further splits into the parser and various parts of the abstract syntax tree (AST) (e.g., modules handling analysis, expressions, functions, types, etc.).
– Provides “backend” facilities eventually (even if not yet fully implemented) for later stages like semantic analysis, type inference, or code generation.
- Compiler CLI (“compiler-cli”):
– Serves as the command-line interface that calls into “compiler-core”.
– Likely handles argument parsing, file reading, and the dispatching to the compilation routines.
- Samples and Configuration:
– Files like “advanced_sample.elk” and “sample.elk” give examples of input language code.
– Cargo configuration files (Cargo.toml, Cargo.lock) and build scripts (justfile) hint at standard Rust project structure and automation.

##### Relationships and Data Flow
- At the highest level, the input starts as ELK source files.
- The CLI reads these source files and then invokes the compiler core.
- Within the compiler-core, the “frontend” first tokenizes the source code, passes it into a parser (located in compiler-core/src/frontend/parser), which builds an AST composed of various nodes (handled by submodules like “ast”, “expressions”, “functions”, etc.).
- Once the AST is built, subsequent stages (e.g., analysis or transformations) can occur using the analysis routines.
- If planned, the output from these stages feeds into further phases such as type checking, optimization, or even code generation.
- External dependencies and future modules (like a potential standard library or Cargo-like project manager mentioned in the README) would also be integrated into this flow.

##### Architectural Patterns and Design Principles
- Modular Design: The library separates concerns by dividing the compiler into “core” and “cli,” and within the core, clearly modularizing parsing, AST construction, and analysis.
- Layered Architecture: Data flows from the CLI into the core, where it is processed by successive layers (tokenization, parsing, AST creation, semantic analysis).
- Reusability & Extensibility: The file tree structure (with directories for AST, parser, types, etc.) shows that the design is meant for further extension (e.g., implementing monads, pattern matching, or type inference later).
- Rust’s Package Management: Cargo files and clear module separation indicate adherence to Rust’s idiomatic practices.

##### Relevant Technologies and Frameworks
- Rust language – the entire project is implemented in Rust.
- Cargo – used for dependency management and building.
- Possibly external libraries (even if not deeply visible from the file tree) might be added later for additional compiler services.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Project Root"
        subgraph "Sample Programs"
            S1("advanced_sample.elk"):::config
            S2("sample.elk"):::config
        end
        subgraph "Configuration Files"
            L("Cargo.toml"):::config
            M("Cargo.lock"):::config
            N("justfile"):::config
        end
    end

    C("Compiler CLI"):::cli
    D("Compiler Core"):::core
    E("Frontend Module"):::frontend
    F("Parser Module"):::module
    G("AST Components"):::module
    H("AST Types"):::module
    I("Analysis Module (Planned)"):::future
    J("Future Backend Components"):::future

    S1 -->|"provides source code"| C
    S2 -->|"provides source code"| C
    L -->|"configures"| C
    M -->|"configures"| C
    N -->|"automates build"| C

    C -->|"invokes compiler"| D
    D -->|"delegates to frontend"| E
    E -->|"performs parsing"| F
    F -->|"builds AST"| G
    G -->|"includes types"| H
    G -->|"feeds analysis"| I
    I -->|"future processing"| J

    click C "https://github.com/rubenjr0/elk/blob/main/compiler-cli/src/main.rs"
    click D "https://github.com/rubenjr0/elk/tree/main/compiler-core/"
    click E "https://github.com/rubenjr0/elk/tree/main/compiler-core/src/frontend/"
    click F "https://github.com/rubenjr0/elk/blob/main/compiler-core/src/frontend/parser.rs"
    click G "https://github.com/rubenjr0/elk/blob/main/compiler-core/src/frontend/ast.rs"
    click H "https://github.com/rubenjr0/elk/tree/main/compiler-core/src/frontend/ast/types/"
    click S1 "https://github.com/rubenjr0/elk/blob/main/advanced_sample.elk"
    click S2 "https://github.com/rubenjr0/elk/blob/main/sample.elk"
    click L "https://github.com/rubenjr0/elk/blob/main/Cargo.toml"
    click M "https://github.com/rubenjr0/elk/blob/main/Cargo.lock"
    click N "https://github.com/rubenjr0/elk/tree/main/justfile"

    classDef cli fill:#f8b195,stroke:#333,stroke-width:2px;
    classDef core fill:#f67280,stroke:#333,stroke-width:2px;
    classDef frontend fill:#c06c84,stroke:#333,stroke-width:2px;
    classDef module fill:#6c5b7b,stroke:#333,stroke-width:2px;
    classDef future fill:#355c7d,stroke:#333,stroke-width:2px;
    classDef config fill:#99b898,stroke:#333,stroke-width:2px;
```
