# alinalihassan/lesma architecture

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

- Interactive diagram: https://gitdiagram.com/alinalihassan/lesma
- Repository: https://github.com/alinalihassan/lesma

## Overview

##### Project Type and Purpose
- Lesma is a compiler for a statically-typed, object-oriented programming language.
- Key features: CLI entry, a modular “liblesma” library (frontend, AST, symbol analysis, backend), standard library files, and extensive tests.
- It also hosts documentation built with Docusaurus.

##### File Structure
- Top-level “src/cli” (`main.cpp`) contains the command-line interface.
- “src/liblesma” breaks down into:
- Frontend (Lexer, Parser)
- AST (AST nodes, Visitor)
- Symbol (SymbolTable, Type, Value)
- Driver (coordinates stages)
- Backend (Codegen using LLVM)
- Common (error handling, utilities)
- “src/stdlib” holds the built-in library that the compiler bundles.
- “tests” directory runs .les source files through the compiler for success/failure.
- “docs” directory is a separate site generator, not part of the compiler runtime.

##### Core Components & Data Flow
a. Components:
- CLI Frontend (src/cli/main.cpp)
- Driver (Driver.cpp/.h)
- Frontend: Lexer → Parser
- AST Module
- Semantic Analyzer (SymbolTable, Type Checking)
- Backend: Codegen (LLVM IR generation)
- Standard Library Loader
- Tests Harness
- External: LLVM library, CMake build, Docusaurus for docs
b. Interactions:
1. User invokes CLI →
2. CLI calls Driver
3. Driver reads .les files (including stdlib) →
4. Lexer tokenizes → Parser builds AST →
5. AST is traversed for symbol resolution & type checking →
6. Backend Codegen translates AST to LLVM IR →
7. LLVM JIT or AOT compiles IR to native code →
8. Executable or object files output
9. Tests invoke CLI/Driver, verify outputs or error messages
c. Architectural Patterns:
- Pipeline (staged compilation)
- Visitor pattern in AST traversal
- Modular separation: CLI vs. Library
d. Technologies:
- C++17, LLVM 15
- CMake & vcpkg for build and dependencies
- Google Benchmark for benchmarks
- Docusaurus + React for docs site

##### Required Elements
- Core compilation stages
- I/O components (CLI, Stdlib, Tests)
- External services (LLVM, Docs)
- Annotations for key patterns (Visitor, Pipeline).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    subgraph "Input / I/O Layer"
        direction TB
        SourceCode["Source Code (.les files)"]:::io
        Stdlib["Standard Library"]:::io
        Tests["Tests Harness"]:::io
    end

    %% Core CLI
    CLI["CLI Frontend"]:::cli
    SourceCode -->|"user input"| CLI
    Tests -->|"run tests"| CLI
    click CLI "https://github.com/alinalihassan/lesma/blob/dev/src/cli/main.cpp"

    %% Orchestrator
    Driver["Driver (Orchestrator)"]:::core
    CLI -->|"invoke"| Driver
    Stdlib -->|"pre-load stdlib"| Driver
    click Driver "https://github.com/alinalihassan/lesma/blob/dev/src/liblesma/Driver/Driver.cpp"
    click Driver "https://github.com/alinalihassan/lesma/blob/dev/src/liblesma/Driver/Driver.h"

    %% Compilation Pipeline
    subgraph "Compilation Pipeline"
        direction TB
        subgraph FrontendModule
            direction TB
            Lexer["Lexer"]:::core
            Parser["Parser"]:::core
        end
        AST["AST Module"]:::core
        Semantic["Semantic Analyzer"]:::core
        Backend["Codegen (LLVM IR)"]:::core
    end

    Driver -->|"reads files"| Lexer
    Lexer -->|"tokens"| Parser
    Parser -->|"AST"| AST
    AST -->|"ASTVisitor"| Semantic
    Semantic -->|"type checked AST"| Backend
    click Lexer "https://github.com/alinalihassan/lesma/blob/dev/src/liblesma/Frontend/Lexer.cpp"
    click Lexer "https://github.com/alinalihassan/lesma/blob/dev/src/liblesma/Frontend/Lexer.h"
    click Parser "https://github.com/alinalihassan/lesma/blob/dev/src/liblesma/Frontend/Parser.cpp"
    click Parser "https://github.com/alinalihassan/lesma/blob/dev/src/liblesma/Frontend/Parser.h"
    click AST "https://github.com/alinalihassan/lesma/blob/dev/src/liblesma/AST/AST.h"
    click AST "https://github.com/alinalihassan/lesma/blob/dev/src/liblesma/AST/ASTVisitor.h"
    click Semantic "https://github.com/alinalihassan/lesma/blob/dev/src/liblesma/Symbol/SymbolTable.cpp"
    click Semantic "https://github.com/alinalihassan/lesma/blob/dev/src/liblesma/Symbol/SymbolTable.h"
    click Semantic "https://github.com/alinalihassan/lesma/blob/dev/src/liblesma/Symbol/Type.h"
    click Semantic "https://github.com/alinalihassan/lesma/blob/dev/src/liblesma/Symbol/Value.h"
    click Backend "https://github.com/alinalihassan/lesma/blob/dev/src/liblesma/Backend/Codegen.cpp"
    click Backend "https://github.com/alinalihassan/lesma/blob/dev/src/liblesma/Backend/Codegen.h"

    %% External LLVM
    LLVM["LLVM Library"]:::external
    Backend -->|"LLVM IR"| LLVM
    LLVM -->|"native code"| Native["Native Binary / .o"]:::output

    %% Common Utilities
    Common["Common Utilities"]:::core
    Driver --> Common
    click Common "https://github.com/alinalihassan/lesma/blob/dev/src/liblesma/Common/LesmaError.h"
    click Common "https://github.com/alinalihassan/lesma/blob/dev/src/liblesma/Common/LesmaVersion.h.in"
    click Common "https://github.com/alinalihassan/lesma/blob/dev/src/liblesma/Common/Utils.cpp"
    click Common "https://github.com/alinalihassan/lesma/blob/dev/src/liblesma/Common/Utils.h"

    %% Token Definitions
    Token["Token Definitions"]:::core
    Lexer --> Token
    click Token "https://github.com/alinalihassan/lesma/blob/dev/src/liblesma/Token/Token.cpp"
    click Token "https://github.com/alinalihassan/lesma/blob/dev/src/liblesma/Token/Token.h"
    click Token "https://github.com/alinalihassan/lesma/blob/dev/src/liblesma/Token/TokenType.h"

    %% Tests Output
    Native -->|"verify output"| Tests

    %% Benchmark Suite
    Bench["Benchmark Suite"]:::io
    Bench -->|"benchmark CLI"| CLI
    click Bench "https://github.com/alinalihassan/lesma/blob/dev/benchmark/benchmark.cpp"

    %% Documentation Subsystem
    subgraph "Documentation Site" 
        direction TB
        Markdown["Markdown Files"]:::docs
        Docusaurus["Docusaurus"]:::docs
        Site["Static Site"]:::docs
    end
    Markdown --> Docusaurus --> Site
    click Markdown "https://github.com/alinalihassan/lesma/tree/dev/docs/"
    
    %% Build System & CI
    subgraph "Build & CI"
        CMake["CMake Config"]:::external
        Vcpkg["vcpkg"]:::external
        GitHub["GitHub Actions"]:::external
        CMake -->|build| CLI
        CMake -->|build| Library["liblesma"]:::core
        Vcpkg --> CMake
        GitHub --> CMake
    end
    click CMake "https://github.com/alinalihassan/lesma/blob/dev/CMakeLists.txt"
    click CMake "https://github.com/alinalihassan/lesma/blob/dev/CMakePresets.json"
    click Vcpkg "https://github.com/alinalihassan/lesma/blob/dev/vcpkg.json"
    click Vcpkg "https://github.com/alinalihassan/lesma/tree/dev/thirdparty/vcpkg/"
    click GitHub "https://github.com/alinalihassan/lesma/tree/dev/.github/workflows/"

    %% Classes
    classDef core fill:#ADD8E6,stroke:#000080,color:#000080;
    classDef cli fill:#90EE90,stroke:#008000,color:#006400;
    classDef external fill:#FFA500,stroke:#FF8C00,color:#8B4513;
    classDef io fill:#FFFF99,stroke:#CCCC00,color:#666600;
    classDef output fill:#D3D3D3,stroke:#A9A9A9,color:#696969;
    classDef docs fill:#D3D3D3,stroke:#A9A9A9,color:#696969;
```
