# giedriusj1/g1 architecture

> Architecture diagram of the GitHub repository giedriusj1/g1, 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/giedriusj1/g1
- Repository: https://github.com/giedriusj1/g1

## Overview

##### Main Components
- Main Application: Represented by src/main.rs, it is the entry point that ties together all components.
- Lexer Module: src/lex.rs handles the tokenization of the input source code.
- Parser / S-Expression Module: src/sexp.rs likely converts token streams into S-expressions or an AST representing the code’s structure.
- Evaluator Module: src/eval.rs implements the evaluation strategy based on the parsed structure.
- Built-in Functions and Intrinsics: The directory built-in (with files such as intrinsics.g1 and test-harness.g1) provide definitions or implementations of the language’s built-in functionality.
- Test Suites: The tests directory (and files with extension .g1) provide examples and unit/integration tests that illustrate how different language constructs should behave. They validate lexing, parsing, evaluation, and built-in behavior.

##### Relationships and Interactions
- Data Flow:
a. A source program (written in the toy elisp dialect) is fed into the system.
b. The Lexer (src/lex.rs) breaks the input into tokens.
c. Tokens are passed to the Parser (src/sexp.rs) which builds a higher-level structure (e.g., S-expressions).
d. The Evaluator (src/eval.rs) processes these S-expressions, using the built-in definitions (from built-in/) as a runtime library.
e. The evaluated result is then output or returned by the system (controlled in src/main.rs).
- The tests further validate these logical flows by feeding example code to the system and ensuring the output matches expectations.

##### Architectural Patterns and Design Principles
- Pipeline Pattern: The design closely follows a linear, step-by-step processing pipeline (lexing → parsing → evaluation).
- Modular Design: Each core functionality (lexer, parser, evaluator) is isolated in its own module, promoting separation of concerns.
- Extensibility: The presence of a built-in directory indicates that new intrinsic or built-in functions can be added modularly, and the test suite is comprehensive, covering many language features.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Input & Main"
        A["Elisp Source Code"]:::start
        B["Main Application (src/main.rs)"]:::processing
    end
    A --> B

    subgraph "Interpreter Pipeline"
        C["Lexer (src/lex.rs)"]:::processing
        D["Parser / S-Expression Module (src/sexp.rs)"]:::processing
        E["Evaluator (src/eval.rs)"]:::processing
        C -->|"tokens"| D
        D -->|"S-expressions"| E
    end
    B --> C
    E --> F["Runtime Output"]:::processing
    E -->|"uses"| G["Built-in Functions & Intrinsics (built-in/)"]:::supportive

    subgraph "Testing"
        H["Test Suites (tests/)"]:::test
    end
    B -->|"validation"| H

    %% Click Events
    click B "https://github.com/giedriusj1/g1/blob/main/src/main.rs"
    click C "https://github.com/giedriusj1/g1/blob/main/src/lex.rs"
    click D "https://github.com/giedriusj1/g1/blob/main/src/sexp.rs"
    click E "https://github.com/giedriusj1/g1/blob/main/src/eval.rs"
    click G "https://github.com/giedriusj1/g1/tree/main/built-in/"
    click H "https://github.com/giedriusj1/g1/tree/main/tests/"

    %% Styles
    classDef start fill:#FADBD8,stroke:#C0392B,stroke-width:2px;
    classDef processing fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef supportive fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef test fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
```
