# fulm-o/stelaro architecture

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

- Interactive diagram: https://gitdiagram.com/fulm-o/stelaro
- Repository: https://github.com/fulm-o/stelaro

## Overview

##### Main Components
- Front End Components:
- steLaro Lexer (src/stelaro_lexer): Handles the lexical analysis with files like lexer.rs, cursor.rs, diagnostics.rs.
- steLaro Parser (src/stelaro_parse): Manages syntactic analysis. Key files include parser.rs, expr.rs, item.rs, etc.
- steLaro AST (src/stelaro_ast): Represents the structure of the source code. Files include ast.rs, token.rs, ty.rs.
- Semantic Analysis and Resolution:
- steLaro Resolve (src/stelaro_resolve): Likely responsible for name resolution and semantic checks.
- Session Management and Context:
- steLaro Session (src/stelaro_session): Contains files such as context.rs and session.rs to manage state and settings during compilation.
- Diagnostics and Error Reporting:
- steLaro Diagnostic (src/stelaro_diagnostic): Deals with error messages and diagnostic information.
- Supporting Utilities:
- steLaro Common (src/stelaro_common): Houses common utilities such as source mapping, span management, and symbols.
- steLaro Interface (src/stelaro_interface): Could offer an API or abstraction layer for interacting with the compiler internals.
- Entry Points:
- src/main.rs and src/lib.rs which likely serve as the application’s entry points and public library interface.

##### Relationships and Data Flows
- The Compilation Pipeline:
- Source Code Input → Lexer: Tokens are generated by reading the source code.
- Lexer Output → Parser: The tokens are fed into the parser to create an AST.
- AST → Semantic Analysis/Resolution: The AST is checked for correctness and enriched with semantic information.
- Throughout these stages, the Diagnostic module is invoked for error reporting and warnings.
- Supporting modules (Common and Interface) are used by all above components to share utilities and offer a unified entry point.

##### Architectural Patterns and Design Principles
- Modularity: Each component (lexer, parser, AST, etc.) is separated into its own module, which encourages maintainability and clear separation of concerns.
- Layered Architecture: The system follows a pipeline-like structure (lexing → parsing → semantic analysis) which is common in compiler design.
- Reusability & Abstraction: The presence of steLaro Common and steLaro Interface modules helps to abstract cross-cutting concerns and expose clean APIs.

##### Relevant Technologies and Frameworks
- Rust: The entire project is written in Rust and uses Cargo for dependency management and build.
- GitHub Workflows: Indicated by the .github directory, which shows a CI/CD configuration (for example, mdbook.yml in the docs indicates documentation generation).

##### Required Elements
- Clear labels:
- Data flow from reading the source code, processing tokens, constructing the AST, performing semantic analysis, and reporting errors.
- Visual differentiation:

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Compilation Pipeline
    subgraph "Compilation Pipeline"
        A["Source Code"]:::pipeline
        B["steLaro Lexer"]:::pipeline
        C["steLaro Parser"]:::pipeline
        D["steLaro AST"]:::pipeline
        E["steLaro Resolve"]:::pipeline
        F["steLaro Session"]:::pipeline
    end

    %% Diagnostics Module
    subgraph "Diagnostics"
        G["steLaro Diagnostic"]:::diagnostic
    end

    %% Supporting Infrastructure
    subgraph "Supporting Infrastructure"
        H["steLaro Common"]:::infra
        I["steLaro Interface"]:::infra
    end

    %% Entry Points
    subgraph "Entry Points"
        J["main.rs"]:::entry
        K["lib.rs"]:::entry
    end

    %% Data Flow Connections in Compilation Pipeline
    J --> A
    K --> A
    A -->|"provides"| B
    B -->|"generatesTokens"| C
    C -->|"constructsAST"| D
    D -->|"semanticAnalysis"| E
    D -->|"sessionManagement"| F

    %% Diagnostics connected from Lexer and Parser
    B -->|"reportsErrors"| G
    C -->|"reportsErrors"| G

    %% Supporting Infrastructure usage references (dotted lines)
    B ---|"utilizes"| H
    C ---|"utilizes"| H
    D ---|"utilizes"| H
    E ---|"utilizes"| H
    F ---|"utilizes"| H

    B ---|"exposesAPI"| I
    C ---|"exposesAPI"| I
    D ---|"exposesAPI"| I
    E ---|"exposesAPI"| I
    F ---|"exposesAPI"| I

    %% Class Declarations for Styling
    classDef pipeline fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef diagnostic fill:#f8d7da,stroke:#333,stroke-width:1px;
    classDef infra fill:#d4edda,stroke:#333,stroke-width:1px;
    classDef entry fill:#fff3cd,stroke:#333,stroke-width:1px;

    %% Click Events
    click B "https://github.com/fulm-o/stelaro/tree/master/src/stelaro_lexer"
    click C "https://github.com/fulm-o/stelaro/tree/master/src/stelaro_parse"
    click D "https://github.com/fulm-o/stelaro/tree/master/src/stelaro_ast"
    click E "https://github.com/fulm-o/stelaro/tree/master/src/stelaro_resolve"
    click F "https://github.com/fulm-o/stelaro/tree/master/src/stelaro_session"
    click G "https://github.com/fulm-o/stelaro/tree/master/src/stelaro_diagnostic"
    click H "https://github.com/fulm-o/stelaro/tree/master/src/stelaro_common"
    click I "https://github.com/fulm-o/stelaro/tree/master/src/stelaro_interface"
    click J "https://github.com/fulm-o/stelaro/blob/master/src/main.rs"
    click K "https://github.com/fulm-o/stelaro/blob/master/src/lib.rs"
```
