# secona/belalang architecture

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

## Overview

##### Project type and purpose
- This is a small interpreted programming language implemented in Rust.
- It uses a modular, multi‑crate workspace:
- **belalang** – the user‑facing CLI/repl/run binary
- **belalang_compiler** – the front­end (lexer, parser, AST, codegen)
- **belalang_vm** – the back­end virtual machine (bytecode, opcode dispatch, memory)
- **belalang_macros** – supporting procedural macros (if any)

##### File structure
- Top‑level Cargo.toml defines a workspace that ties everything together.
- **/crates/belalang** contains the binary entrypoints (`main.rs`, `repl.rs`, `run.rs`).
- **/crates/belalang_compiler** is subdivided into:
- `tokens` (lexer)
- `ast` (parser & AST nodes)
- `codegen` (bytecode generation & disassembler)
- **/crates/belalang_vm** contains VM core (`vm.rs`), bytecode definitions, memory management modules (`heap`, `stack`), and built­in objects.
- **/crates/belalang_macros** holds any Rust proc‑macros used by the compiler or VM.

##### Essential details to capture
- The workspace relationship (root Cargo → individual crates).
- Build‑time vs. run‑time components (macros vs. VM).
- Data transformation pipeline from source code to program execution.
- Interaction between CLI and runtime engine.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI / REPL" 
        direction TB
        Main["main.rs"]:::cli
        REPL["repl.rs"]:::cli
        Run["run.rs"]:::cli
    end

    %% Front-End Layer
    subgraph "Compiler Front-End" 
        direction TB
        subgraph "Tokens (Lexer)" 
            direction TB
            TokensMod["mod.rs"]:::frontend
            Lexer["lexer.rs"]:::frontend
        end
        subgraph "AST & Parser" 
            direction TB
            ASTMod["mod.rs"]:::frontend
            Parser["parser.rs"]:::frontend
            Expr["expressions.rs"]:::frontend
            Stmt["statements.rs"]:::frontend
            Program["program.rs"]:::frontend
        end
        Error["error.rs"]:::frontend
        LibComp["lib.rs"]:::frontend
    end

    %% Code Generation Layer
    subgraph "Code Generator" 
        direction TB
        CGMod["mod.rs"]:::codegen
        Scope["scope.rs"]:::codegen
        Disasm["disassembler.rs"]:::codegen
    end

    %% VM Layer
    subgraph "Virtual Machine" 
        direction TB
        subgraph "Core" 
            direction TB
            VMCore["vm.rs"]:::vm
            Bytecode["bytecode.rs"]:::vm
            Opcode["opcode.rs"]:::vm
            CoreMod["core.rs"]:::vm
            LibVM["lib.rs"]:::vm
        end
        subgraph "Memory Management" 
            direction TB
            Heap["heap.rs"]:::vm
            Stack["stack.rs"]:::vm
            MemMod["mem.rs"]:::vm
        end
        subgraph "Built-in Objects" 
            direction TB
            Array["array.rs"]:::vm
            BaseObj["base.rs"]:::vm
            BoolObj["boolean.rs"]:::vm
            IntObj["integer.rs"]:::vm
            PtrObj["ptr.rs"]:::vm
            StringObj["string.rs"]:::vm
            ObjMod["objects.rs"]:::vm
        end
        Prel["prelude.rs"]:::vm
        VMErr["errors.rs"]:::vm
    end

    %% Procedural Macros Layer
    Macro["lib.rs"]:::macros

    %% Examples and Tests
    subgraph "Examples" 
        direction TB
        Ex0["00_hello_belalang.bel"]:::examples
        Ex1["01_variables.bel"]:::examples
        Ex2["02_conditionals.bel"]:::examples
        Ex3["03_functions.bel"]:::examples
        Ex4["04_while_loops.bel"]:::examples
        Ex5["05_factorial.bel"]:::examples
    end

    subgraph "Tests"
        direction TB
        TCLI["crates/belalang/tests/examples.rs"]:::tests
        TCompLex["crates/belalang_compiler/tests/lexer.rs"]:::tests
        TCompExpr["crates/belalang_compiler/tests/expressions.rs"]:::tests
        TCompStmt["crates/belalang_compiler/tests/statements.rs"]:::tests
        TCompAll["crates/belalang_compiler/tests/compiler.rs"]:::tests
        TVMObj["crates/belalang_vm/tests/objects.rs"]:::tests
        TVMCore["crates/belalang_vm/tests/vm.rs"]:::tests
    end

    %% Data Flow
    Main -->|"source text"| TokensMod
    Lexer -->|"Vec<Token>"| Parser
    Parser -->|"AST Node"| CGMod
    CGMod -->|"Vec<BytecodeInstr>"| VMCore
    VMCore -->|"execute"| Run
    REPL -->|"interactive loop"| Lexer
    Macro -.->|build-time| LibComp
    Macro -.->|build-time| LibVM
    Ex0 -.-> Main
    Ex1 -.-> Main
    Ex2 -.-> Main
    Ex3 -.-> Main
    Ex4 -.-> Main
    Ex5 -.-> Main
    TCLI -.-> Main
    TCompLex -.-> Lexer
    TCompExpr -.-> Expr
    TCompStmt -.-> Stmt
    TCompAll -.-> CGMod
    TVMObj -.-> ObjMod
    TVMCore -.-> VMCore

    %% Click Events
    click Main "https://github.com/secona/belalang/blob/main/crates/belalang/src/main.rs"
    click REPL "https://github.com/secona/belalang/blob/main/crates/belalang/src/repl.rs"
    click Run "https://github.com/secona/belalang/blob/main/crates/belalang/src/run.rs"
    click Lexer "https://github.com/secona/belalang/blob/main/crates/belalang_compiler/src/tokens/lexer.rs"
    click TokensMod "https://github.com/secona/belalang/blob/main/crates/belalang_compiler/src/tokens/mod.rs"
    click Parser "https://github.com/secona/belalang/blob/main/crates/belalang_compiler/src/ast/parser.rs"
    click Expr "https://github.com/secona/belalang/blob/main/crates/belalang_compiler/src/ast/expressions.rs"
    click Stmt "https://github.com/secona/belalang/blob/main/crates/belalang_compiler/src/ast/statements.rs"
    click Program "https://github.com/secona/belalang/blob/main/crates/belalang_compiler/src/ast/program.rs"
    click ASTMod "https://github.com/secona/belalang/blob/main/crates/belalang_compiler/src/ast/mod.rs"
    click CGMod "https://github.com/secona/belalang/blob/main/crates/belalang_compiler/src/codegen/mod.rs"
    click Scope "https://github.com/secona/belalang/blob/main/crates/belalang_compiler/src/codegen/scope.rs"
    click Disasm "https://github.com/secona/belalang/blob/main/crates/belalang_compiler/src/codegen/disassembler.rs"
    click Error "https://github.com/secona/belalang/blob/main/crates/belalang_compiler/src/error.rs"
    click LibComp "https://github.com/secona/belalang/blob/main/crates/belalang_compiler/src/lib.rs"
    click Macro "https://github.com/secona/belalang/blob/main/crates/belalang_macros/src/lib.rs"
    click VMCore "https://github.com/secona/belalang/blob/main/crates/belalang_vm/src/core/vm.rs"
    click Bytecode "https://github.com/secona/belalang/blob/main/crates/belalang_vm/src/core/bytecode.rs"
    click Opcode "https://github.com/secona/belalang/blob/main/crates/belalang_vm/src/core/opcode.rs"
    click CoreMod "https://github.com/secona/belalang/blob/main/crates/belalang_vm/src/core.rs"
    click LibVM "https://github.com/secona/belalang/blob/main/crates/belalang_vm/src/lib.rs"
    click Heap "https://github.com/secona/belalang/blob/main/crates/belalang_vm/src/mem/heap.rs"
    click Stack "https://github.com/secona/belalang/blob/main/crates/belalang_vm/src/mem/stack.rs"
    click MemMod "https://github.com/secona/belalang/blob/main/crates/belalang_vm/src/mem.rs"
    click Array "https://github.com/secona/belalang/blob/main/crates/belalang_vm/src/objects/array.rs"
    click BaseObj "https://github.com/secona/belalang/blob/main/crates/belalang_vm/src/objects/base.rs"
    click BoolObj "https://github.com/secona/belalang/blob/main/crates/belalang_vm/src/objects/boolean.rs"
    click IntObj "https://github.com/secona/belalang/blob/main/crates/belalang_vm/src/objects/integer.rs"
    click PtrObj "https://github.com/secona/belalang/blob/main/crates/belalang_vm/src/objects/ptr.rs"
    click StringObj "https://github.com/secona/belalang/blob/main/crates/belalang_vm/src/objects/string.rs"
    click ObjMod "https://github.com/secona/belalang/blob/main/crates/belalang_vm/src/objects.rs"
    click Prel "https://github.com/secona/belalang/blob/main/crates/belalang_vm/src/prelude.rs"
    click VMErr "https://github.com/secona/belalang/blob/main/crates/belalang_vm/src/errors.rs"
    click Ex0 "https://github.com/secona/belalang/blob/main/examples/00_hello_belalang.bel"
    click Ex1 "https://github.com/secona/belalang/blob/main/examples/01_variables.bel"
    click Ex2 "https://github.com/secona/belalang/blob/main/examples/02_conditionals.bel"
    click Ex3 "https://github.com/secona/belalang/blob/main/examples/03_functions.bel"
    click Ex4 "https://github.com/secona/belalang/blob/main/examples/04_while_loops.bel"
    click Ex5 "https://github.com/secona/belalang/blob/main/examples/05_factorial.bel"
    click TCLI "https://github.com/secona/belalang/blob/main/crates/belalang/tests/examples.rs"
    click TCompLex "https://github.com/secona/belalang/blob/main/crates/belalang_compiler/tests/lexer.rs"
    click TCompExpr "https://github.com/secona/belalang/blob/main/crates/belalang_compiler/tests/expressions.rs"
    click TCompStmt "https://github.com/secona/belalang/blob/main/crates/belalang_compiler/tests/statements.rs"
    click TCompAll "https://github.com/secona/belalang/blob/main/crates/belalang_compiler/tests/compiler.rs"
    click TVMObj "https://github.com/secona/belalang/blob/main/crates/belalang_vm/tests/objects.rs"
    click TVMCore "https://github.com/secona/belalang/blob/main/crates/belalang_vm/tests/vm.rs"

    %% Styles
    classDef cli fill:#D8BFD8,stroke:#9370DB,color:#000
    classDef frontend fill:#ADD8E6,stroke:#0000FF,color:#000
    classDef codegen fill:#98FB98,stroke:#008000,color:#000
    classDef vm fill:#FFDAB9,stroke:#FF8C00,color:#000
    classDef macros fill:#FFE4B5,stroke:#DAA520,color:#000
    classDef examples fill:#F0FFF0,stroke:#32CD32,color:#000
    classDef tests fill:#FFFACD,stroke:#FFD700,color:#000
```
