# lostella/loscheme architecture

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

- Interactive diagram: https://gitdiagram.com/lostella/loscheme
- Repository: https://github.com/lostella/loscheme

## Overview

##### Project Type and Purpose
- **Type**: A language interpreter for Scheme, written in Rust, with both CLI (native) and Web (WASM) front ends.
- **Purpose**:
- Offer a REPL and script-runner for Scheme programs on the command line.

##### File Structure
- **Top-Level Executables**
- `src/bin/loscheme.rs`: CLI entry point.
- `src/web.rs` + `web/index.html`: WebAssembly front end.
- **Core Library** (`src/lib.rs`)
Breaks down into modules:
- `parser.rs`: Source → AST
- `treewalk/`: AST evaluator + standard library (`builtin.rs`)
- `rationals.rs`: Numeric type
- `run.rs`: Orchestrates parsing + evaluation in REPL/script mode
- `rv32.rs`: (Optional) support for RV32 architecture?
- `errors.rs`: Error definitions and handling
- **Scripts** (`scripts/*.scm`): Example Scheme programs that exercise core features.
- **Tests** (`tests/test.rs`): Integration tests for interpreter behavior.
- **CI** (`.github/workflows/ci.yml`): Defines build & test pipeline.
- **Cargo.toml**: Dependency and build configuration.

##### Extract Insights from the README
- CLI usage: `cargo run --release` → REPL.
- Script execution: `cargo run -- path/to/script.scm`.
- Browser: precompiled WebAssembly available on GitHub Pages.

##### Main Components
a. **Front-ends**
- **CLI Binary** (`loscheme`)
- **WebAssembly Module** (loaded by `index.html`)
b. **Core Interpreter Library**
- **Parser** → produces AST
- **Evaluator (Tree-walker)** → executes AST
- **Built-ins** (arithmetic, list ops, I/O)
- **Numeric subsystem** (`rationals`)
- **Runtime / REPL loop** (`run.rs`)
- **Error handler**
c. **Supporting Artifacts**
- **Scripts** directory (external inputs)
- **Tests**
- **CI pipeline**
- **Cargo build system**

##### Interactions and Data Flow
- User types input (REPL) or invokes script →
the **CLI** or **Browser** front-end calls into →
**run.rs** → **parser** → AST → **treewalker** + **built-ins** → result →
back to front-end → stdout or browser UI.
- The **Cargo toolchain** orchestrates compilation to native binary or WASM.
- **CI** checks out code, runs `cargo test` and `cargo build --target wasm32-unknown-unknown`, then deploys.

##### Architectural Patterns & Principles
- **Modular Separation**: clear split between front-ends and core library.
- **Single Binary / Single WASM Module**: both share the same core.
- **Tree-walk Interpreter**: parser produces AST, then a single pass evaluator.
- **Rust Ownership & Error Handling**: typed errors module.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Front-ends
    subgraph "Front-ends"
        CLI["CLI Front-end<br/>(loscheme binary)"]:::frontend
        BrowserWasm["WASM Module<br/>(src/web.rs)"]:::frontend
        Loader["Loader<br/>(index.html)"]:::frontend
    end

    %% Core Interpreter Library
    subgraph "Core Interpreter Library"
        Runner["REPL & Script Runner<br/>(run.rs)"]:::core
        Parser["Parser<br/>(parser.rs)"]:::core
        AST["AST"]:::core
        Evaluator["Evaluator<br/>(Tree-walker)"]:::core
        Builtins["Built-ins<br/>(builtin.rs)"]:::core
        Numeric["Numeric Subsystem<br/>(rationals.rs)"]:::core
        Errors["Error Handling<br/>(errors.rs)"]:::core
        RV32["RV32 Support<br/>(rv32.rs)"]:::core
    end

    %% Auxiliary Components
    subgraph "Auxiliary Components"
        Scripts["Example Scheme Scripts<br/>(scripts/*.scm)"]:::aux
        Tests["Integration Tests<br/>(tests/test.rs)"]:::aux
        CI["CI Pipeline<br/>(.github/workflows/ci.yml)"]:::aux
        Cargo["Build Config<br/>(Cargo.toml)"]:::aux
        Stdout["Stdout"]:::aux
        DOM["Browser UI (DOM)"]:::aux
    end

    %% Data Flows
    Scripts -->|"load script"| CLI
    Scripts -->|"load script"| BrowserWasm
    CLI -->|"invoke"| Runner
    BrowserWasm -->|"invoke"| Runner
    Runner -->|"parse()"| Parser
    Parser -->|"produce AST"| AST
    AST -->|"evaluate()"| Evaluator
    Evaluator -->|"use built-ins"| Builtins
    Evaluator -->|"use numeric ops"| Numeric
    Evaluator -->|"error handling"| Errors
    RV32 -.->|"optional support"| Evaluator
    Evaluator -->|"result"| Runner
    Runner -->|"output"| Stdout
    BrowserWasm -->|"output"| DOM

    CI -->|"runs tests & builds"| Cargo
    CI -->|"runs tests"| Tests

    %% Click Events
    click CLI "https://github.com/lostella/loscheme/blob/main/src/bin/loscheme.rs"
    click BrowserWasm "https://github.com/lostella/loscheme/blob/main/src/web.rs"
    click Loader "https://github.com/lostella/loscheme/blob/main/web/index.html"
    click Parser "https://github.com/lostella/loscheme/blob/main/src/parser.rs"
    click Evaluator "https://github.com/lostella/loscheme/blob/main/src/treewalk/mod.rs"
    click Builtins "https://github.com/lostella/loscheme/blob/main/src/treewalk/builtin.rs"
    click Numeric "https://github.com/lostella/loscheme/blob/main/src/rationals.rs"
    click Runner "https://github.com/lostella/loscheme/blob/main/src/run.rs"
    click Errors "https://github.com/lostella/loscheme/blob/main/src/errors.rs"
    click RV32 "https://github.com/lostella/loscheme/blob/main/src/rv32.rs"
    click Scripts "https://github.com/lostella/loscheme/tree/main/scripts"
    click Tests "https://github.com/lostella/loscheme/blob/main/tests/test.rs"
    click CI "https://github.com/lostella/loscheme/blob/main/.github/workflows/ci.yml"
    click Cargo "https://github.com/lostella/loscheme/blob/main/Cargo.toml"

    %% Styles
    classDef frontend fill:#a8e6cf,stroke:#379683,color:#05386b
    classDef core fill:#d0e1f9,stroke:#4a69bd,color:#1e272e
    classDef aux fill:#f0f0f0,stroke:#888,color:#333
```
