# bfierz/lox-rs architecture

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

- Interactive diagram: https://gitdiagram.com/bfierz/lox-rs
- Repository: https://github.com/bfierz/lox-rs

## Overview

##### Project type and purpose
- This repository is a command-line tool (“loxrun”) written in Rust that interprets Lox scripts. It follows the structure of a language interpreter: source code scanner (lexer), parser (AST builder), and an interpreter that walks the AST.
- The primary purpose is to provide a runnable Lox interpreter (see examples/*.lox) and to demonstrate Rust development using DevContainers and CI.

##### File structure
- Top-level configuration:
- .devcontainer/, .vscode/: Development environment (VS Code DevContainer)
- .github/workflows/verify.yml: CI job for building/testing
- scripts/post_setup.sh: Container setup steps
- Core application (“loxrun” folder):
- Cargo.toml/Cargo.lock: Rust project metadata and dependencies
- src/main.rs: CLI entrypoint
- src/scanner.rs: Tokenizes Lox source
- src/parser.rs: Builds AST of expressions/statements
- src/expression.rs & src/stmt.rs: AST node definitions
- src/tokens.rs: Token type definitions
- src/interpreter.rs: AST walker that executes code
- src/printer.rs: (Optional) AST pretty-printer
- src/callable.rs: Function/callable abstractions
- Examples directory: sample .lox scripts to test/run
- verification/: patch files for testing language conformance

##### README for additional insights
- README focuses on providing a Rust DevContainer setup; it does not describe system architecture, so we infer architecture purely from the file layout and naming.

- Central pipeline:
[Examples (input)] → [Scanner] → [Parser] → [AST Nodes] → [Interpreter] → [Console Output]
Optionally branch from AST Nodes → [Printer] for debugging
- Development/config (blue)
- CI (green)
- Runtime pipeline (orange)
- Build system (gray)

##### Final advice
- Be detailed: include every module as a separate component in the pipeline.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CI Pipeline
    subgraph "CI Pipeline"
        CI["GitHub Actions Workflow"]:::ci
    end
    click CI "https://github.com/bfierz/lox-rs/blob/main/.github/workflows/verify.yml"

    %% Developer Environment
    subgraph "Developer Environment"
        DC["DevContainer Configuration"]:::dev
        VS["VS Code Settings"]:::dev
        PS["Post-setup Script"]:::dev
    end
    click DC "https://github.com/bfierz/lox-rs/blob/main/.devcontainer/devcontainer.json"
    click VS "https://github.com/bfierz/lox-rs/tree/main/.vscode/"
    click PS "https://github.com/bfierz/lox-rs/blob/main/scripts/post_setup.sh"

    %% Build System
    subgraph "Build System"
        CargoToml["Cargo Manifest"]:::build
        CargoLock["Cargo Lockfile"]:::build
    end
    click CargoToml "https://github.com/bfierz/lox-rs/blob/main/loxrun/Cargo.toml"
    click CargoLock "https://github.com/bfierz/lox-rs/blob/main/loxrun/Cargo.lock"

    %% Verification Patches
    Verification["Verification Patches"]:::data
    click Verification "https://github.com/bfierz/lox-rs/tree/main/verification/"

    %% Runtime Pipeline
    subgraph "Runtime Pipeline"
        Examples["Input Lox Scripts"]:::data
        Scanner["Scanner Module\n(scanner.rs)"]:::runtime
        Parser["Parser Module\n(parser.rs)"]:::runtime
        Expr["Expression AST\n(expression.rs)"]:::runtime
        Stmt["Statement AST\n(stmt.rs)"]:::runtime
        Tokens["Token Definitions\n(tokens.rs)"]:::runtime
        Interpreter["Interpreter\n(interpreter.rs)"]:::runtime
        Printer["AST Pretty Printer\n(printer.rs)"]:::runtime
        Callable["Callable Abstractions\n(callable.rs)"]:::runtime
        Output["Console Output"]:::runtime
    end
    click Examples "https://github.com/bfierz/lox-rs/tree/main/examples/"
    click Scanner "https://github.com/bfierz/lox-rs/blob/main/loxrun/src/scanner.rs"
    click Parser "https://github.com/bfierz/lox-rs/blob/main/loxrun/src/parser.rs"
    click Expr "https://github.com/bfierz/lox-rs/blob/main/loxrun/src/expression.rs"
    click Stmt "https://github.com/bfierz/lox-rs/blob/main/loxrun/src/stmt.rs"
    click Tokens "https://github.com/bfierz/lox-rs/blob/main/loxrun/src/tokens.rs"
    click Interpreter "https://github.com/bfierz/lox-rs/blob/main/loxrun/src/interpreter.rs"
    click Printer "https://github.com/bfierz/lox-rs/blob/main/loxrun/src/printer.rs"
    click Callable "https://github.com/bfierz/lox-rs/blob/main/loxrun/src/callable.rs"

    %% Connections
    CI -->|"build & test"| CargoToml
    CI -->|"apply patches"| Verification
    DC -->|"configure env"| CargoToml
    VS -->|"settings loaded"| DC
    PS -->|"post-setup"| DC

    CargoToml -->|"manage build"| Scanner
    CargoToml -->|"manage build"| Parser

    Examples -->|"source input"| Scanner
    Scanner -->|"tokens"| Parser
    Tokens -->|"definitions"| Scanner
    Parser -->|"AST nodes"| Interpreter
    Parser -->|"uses"| Expr
    Parser -->|"uses"| Stmt
    Interpreter -->|"executes"| Output
    Interpreter -->|"invokes"| Callable
    Expr -->|"defines tree"| Interpreter
    Stmt -->|"defines tree"| Interpreter
    Parser -->|"uses"| Tokens
    Expr -->|"visualize"| Printer
    Stmt -->|"visualize"| Printer
    Interpreter -->|"optional dump"| Printer

    %% Styles
    classDef dev fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef ci fill:#D0FFD6,stroke:#28a745,stroke-width:1px
    classDef build fill:#E0E0E0,stroke:#636363,stroke-width:1px
    classDef runtime fill:#FFE4B3,stroke:#d97706,stroke-width:1px
    classDef data fill:#FFF2CC,stroke:#b08900,stroke-width:1px
```
