# mattwparas/steel architecture

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

- Interactive diagram: https://gitdiagram.com/mattwparas/steel
- Repository: https://github.com/mattwparas/steel

## Overview

##### Project type and purpose
- This is a monorepo for “Steel,” an embeddable Scheme dialect implemented in Rust.
- It provides:
- A parser and compiler pipeline that produces bytecode (and optional JIT),
- A VM engine exposed as a library (for embedding),
- A standalone CLI REPL,
- A language server (LSP) for editors,
- A standard library written in Scheme (the “cogs” directory),
- Documentation generation and book (mdBook),
- Examples, benchmarks, and tooling (xtask, Docker, Nix).

##### File structure
- Top-level directories:
- crates/ – Rust workspace crates (steel-core, steel-parser, steel-repl, steel-language-server, steel-doc, steel-derive, steel-gen, etc.)
- cogs/ – Scheme-level standard library modules and tests
- libs/ – Community/contrib libraries (markdown, regex, sqlite, HTTP, webserver, websockets, etc.)
- docs/ – mdBook documentation sources and theme
- examples/, steel-examples/, r7rs-benchmarks/, benchmarks/ – sample programs and performance tests
- src/ – likely legacy or top-level CLI glue (src/lib.rs, src/main.rs)
- Dockerfile, GitHub workflows, Nix files, Cargo.toml (workspace config), build.rs, xtask – build and CI tooling

##### Key insights from README
- Steel is R5RS-compliant with a powerful macro system (syntax-rules), contracts, transducers, and a bytecode VM with optional JIT.
- Exposes a Rust API (register_fn, register_type, run, extract).
- CLI REPL and an online playground exist.
- Language Server integrates with editors via LSP for diagnostics and auto-completion.

##### Be detailed but focused
- Every Rust crate or group them by function (parsing, core, repl, lsp, docs).
- How the cogs standard-library fits into module loading inside the VM.
- Embedding boundary clearly: anything calling Engine is an external consumer.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Input
    Source["Scheme Source"]:::external

    %% Parsing & Compilation Layer
    subgraph "Parsing & Compilation"
        direction TB
        Parser["Parser"]:::parse
        MacroExpander["Macro Expander & Compiler Passes"]:::parse
        Compiler["Compiler (AST→Bytecode)"]:::parse
        BytecodeGen["Bytecode CodeGen"]:::parse
    end

    %% Execution Engine Layer
    subgraph "Execution Engine"
        direction TB
        VM["Bytecode VM"]:::engine
        JIT["JIT Compiler"]:::engine
        EngineAPI["Engine API"]:::engine
        Heap["Heap"]:::store
        ModuleCache["Module Cache"]:::store
    end

    %% Host Interfaces
    subgraph "Host Interfaces"
        direction TB
        REPL["REPL/CLI"]:::frontend
        LSP["Language Server (LSP)"]:::frontend
        Embedding["Embedding in Apps"]:::frontend
    end

    %% Standard Library
    StdLib["Std Library (cogs)"]:::data

    %% Tooling & Documentation
    subgraph "Tools & Documentation"
        direction TB
        Docs["Doc Generator & Book"]:::tools
        Examples["Examples"]:::tools
        Benchmarks["Benchmarks"]:::tools
        Tooling["Build & CI Tooling"]:::tools
    end

    %% Data Flow
    Source --> Parser --> MacroExpander --> Compiler --> BytecodeGen --> VM
    VM --> Heap
    VM --> ModuleCache
    VM --> JIT
    JIT --> VM
    VM --> EngineAPI

    %% Standard library loading
    StdLib --> VM

    %% Consumers of Engine API
    EngineAPI --> REPL
    EngineAPI --> LSP
    EngineAPI --> Embedding

    %% LSP also uses Parser & Compiler for diagnostics
    LSP --> Parser
    LSP --> Compiler

    %% Examples and Benchmarks use Engine API
    Examples --> EngineAPI
    Benchmarks --> EngineAPI

    %% Documentation reads crates metadata & docs sources
    Docs --> Parser
    Docs --> EngineAPI

    %% Tooling peripheral
    Tooling -.-> Parser
    Tooling -.-> VM
    Tooling -.-> Docs

    %% Click Events
    click Parser "https://github.com/mattwparas/steel/blob/master/crates/steel-parser/src/parser.rs"
    click MacroExpander "https://github.com/mattwparas/steel/tree/master/crates/steel-core/src/compiler/passes"
    click Compiler "https://github.com/mattwparas/steel/blob/master/crates/steel-core/src/compiler/mod.rs"
    click BytecodeGen "https://github.com/mattwparas/steel/blob/master/crates/steel-core/src/compiler/code_gen.rs"
    click VM "https://github.com/mattwparas/steel/blob/master/crates/steel-core/src/steel_vm/vm.rs"
    click JIT "https://github.com/mattwparas/steel/blob/master/crates/steel-core/src/jit/mod.rs"
    click EngineAPI "https://github.com/mattwparas/steel/blob/master/crates/steel-core/src/steel_vm/engine.rs"
    click REPL "https://github.com/mattwparas/steel/blob/master/crates/steel-repl/src/repl.rs"
    click LSP "https://github.com/mattwparas/steel/blob/master/crates/steel-language-server/src/main.rs"
    click StdLib "https://github.com/mattwparas/steel/tree/master/cogs/"
    click Docs "https://github.com/mattwparas/steel/blob/master/crates/steel-doc/src/main.rs"
    click Examples "https://github.com/mattwparas/steel/tree/master/examples/"
    click Benchmarks "https://github.com/mattwparas/steel/tree/master/benchmarks/"
    click Tooling "https://github.com/mattwparas/steel/blob/master/crates/xtask/src/main.rs"

    %% Styles
    classDef parse fill:#E0F7FA,stroke:#00BCD4,color:#000
    classDef engine fill:#E8F5E9,stroke:#4CAF50,color:#000
    classDef frontend fill:#FFF3E0,stroke:#FF9800,color:#000
    classDef tools fill:#ECEFF1,stroke:#90A4AE,color:#000
    classDef external fill:#F3E5F5,stroke:#9C27B0,color:#000
    classDef data fill:#FFEBEE,stroke:#F44336,color:#000
    classDef store fill:#FFFDE7,stroke:#FFEB3B,color:#000
```
