# terror/val architecture

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

- Interactive diagram: https://gitdiagram.com/terror/val
- Repository: https://github.com/terror/val

## Overview

##### Project type and purpose
- “val” is a multi‐target language runtime and CLI tool written in Rust. It provides:
- A command‑line REPL/file evaluator for an arbitrary‑precision calculator language
- A Rust library (core engine) exposed programmatically
- A WebAssembly target (crates/val‑wasm) to embed the engine in browsers
- A React/TypeScript web playground (www) that loads the WASM module
- Auxiliary tools include a Python example‑generator, benchmarks, tests, and CI/CD pipelines.

##### File structure
- Top level: Rust package (Cargo.toml), src/ (core CLI & lib), benches/, tests/, examples/, tools/, crates/val-wasm/, www/
- src/ contains modules for:
Parser (parser.rs + GRAMMAR.txt using chumsky)
AST (ast.rs + ast_node.rs)
Evaluator & environment (evaluator.rs, environment.rs)
Highlighter (highlighter.rs)
Error handling (error.rs), value types (value.rs), built‑ins, etc.
- crates/val-wasm: compiles the same engine to WebAssembly with wasm‑bindgen
- www/: Vite‐bundled React/TS app
Loads val_bg.wasm + JS glue (val.js, val.d.ts)
Editor + AST visualizer + settings dialog + example loader
- tools/example‑generator: Python CLI to sync/generate .val example files
- .github/workflows: CI for Rust build/test, WASM build, Web build, and release

##### README for additional insights
- Confirms architecture: CLI uses rustyline for REPL, core engine leverages chumsky & ariadne, WASM binding for web, built‑ins listed
- No external database—pure in‑memory evaluation pipeline

##### Detail without over‑complicating
- WASM crate as “same engine → WebAssembly”
- Flow of .val example files from disk into both frontends
- CI pipelines feeding into each build target

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Frontend
    subgraph "CLI Frontend"
        CLI_main["main.rs"]:::cli
        CLI_args["arguments.rs"]:::cli
        CLI_config["config.rs"]:::cli
    end

    %% Core Engine
    subgraph "Core Engine (Rust)" 
        Parser["parser.rs"]:::core
        Grammar["GRAMMAR.txt"]:::core
        AST["ast.rs"]:::core
        Evaluator["evaluator.rs"]:::core
        Env["environment.rs"]:::core
        Highlighter["highlighter.rs"]:::core
        ErrorHandling["error.rs"]:::core
        ValueTypes["value.rs"]:::core
        Builtins["Built-ins & Utils"]:::core
    end

    %% WASM Binding
    subgraph "WASM Binding"
        WASM_lib["lib.rs"]:::wasm
        WASM_ast["ast_node.rs"]:::wasm
        WASM_err["error.rs"]:::wasm
        WASM_range["range.rs"]:::wasm
    end

    %% Web Playground
    subgraph "Web Playground"
        App_main["main.tsx"]:::web
        App_root["App.tsx"]:::web
        Components["components/*"]:::web
        UI_prims["components/ui/*"]:::web
        Hooks["use-persisted-state.tsx"]:::web
        Provider["editor-settings-provider.tsx"]:::web
        Web_highlight["highlight.ts"]:::web
        WASM_module["val_bg.wasm + val.js + val.d.ts"]:::web
    end

    %% Tooling & CI
    subgraph "Tooling & CI"
        ExampleGen["main.py"]:::tools
        Benchmarks["main.rs (benches)"]:::tools
        Tests["integration.rs"]:::tools
        CI["GitHub Actions workflows"]:::tools
    end

    %% Relationships
    CLI_main -->|"parses"| Parser
    CLI_main -->|"evaluates"| Evaluator
    Parser --> AST
    AST --> Evaluator
    Evaluator --> Env
    Evaluator --> ValueTypes
    Evaluator --> Builtins
    Parser --> ErrorHandling
    CLI_main --> Highlighter

    WASM_lib --> Parser
    WASM_lib --> Evaluator
    WASM_lib --> ErrorHandling
    WASM_ast --> AST
    WASM_range --> Builtins

    WASM_module --> WASM_lib
    Components --> WASM_module
    Components --> Web_highlight
    App_main --> App_root
    App_root --> Components
    App_root --> UI_prims
    App_root --> Hooks
    App_root --> Provider

    ExampleGen -->|"generates .val files"| CLI_main
    ExampleGen -->|"generates .val files"| Components
    Benchmarks --> Parser
    Tests --> Evaluator
    CI --> CLI_main
    CI --> WASM_lib
    CI --> App_main

    %% Click Events
    click CLI_main "https://github.com/terror/val/blob/master/src/main.rs"
    click CLI_args "https://github.com/terror/val/blob/master/src/arguments.rs"
    click CLI_config "https://github.com/terror/val/blob/master/src/config.rs"
    click Parser "https://github.com/terror/val/blob/master/src/parser.rs"
    click Grammar "https://github.com/terror/val/blob/master/GRAMMAR.txt"
    click AST "https://github.com/terror/val/blob/master/src/ast.rs"
    click Evaluator "https://github.com/terror/val/blob/master/src/evaluator.rs"
    click Env "https://github.com/terror/val/blob/master/src/environment.rs"
    click Highlighter "https://github.com/terror/val/blob/master/src/highlighter.rs"
    click ErrorHandling "https://github.com/terror/val/blob/master/src/error.rs"
    click ValueTypes "https://github.com/terror/val/blob/master/src/value.rs"
    click Builtins "https://github.com/terror/val/blob/master/src/function.rs"
    click WASM_lib "https://github.com/terror/val/blob/master/crates/val-wasm/src/lib.rs"
    click WASM_ast "https://github.com/terror/val/blob/master/crates/val-wasm/src/ast_node.rs"
    click WASM_err "https://github.com/terror/val/blob/master/crates/val-wasm/src/error.rs"
    click WASM_range "https://github.com/terror/val/blob/master/crates/val-wasm/src/range.rs"
    click App_main "https://github.com/terror/val/blob/master/www/src/main.tsx"
    click App_root "https://github.com/terror/val/blob/master/www/src/App.tsx"
    click Components "https://github.com/terror/val/tree/master/www/src/components"
    click UI_prims "https://github.com/terror/val/tree/master/www/src/components/ui"
    click Hooks "https://github.com/terror/val/blob/master/www/src/hooks/use-persisted-state.tsx"
    click Provider "https://github.com/terror/val/blob/master/www/src/providers/editor-settings-provider.tsx"
    click Web_highlight "https://github.com/terror/val/blob/master/www/src/lib/highlight.ts"
    click WASM_module "https://github.com/terror/val/tree/master/www/packages/val-wasm"
    click ExampleGen "https://github.com/terror/val/blob/master/tools/example-generator/main.py"
    click Benchmarks "https://github.com/terror/val/blob/master/benches/main.rs"
    click Tests "https://github.com/terror/val/blob/master/tests/integration.rs"
    click CI "https://github.com/terror/val/tree/master/.github/workflows"

    %% Styles
    classDef core fill:#e2f5e9,stroke:#2e7d32,stroke-width:2px
    classDef cli fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
    classDef wasm fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
    classDef web fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px
    classDef tools fill:#eceff1,stroke:#546e7a,stroke-width:2px
```
