# beariish/bolt architecture

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

- Interactive diagram: https://gitdiagram.com/beariish/bolt
- Repository: https://github.com/beariish/bolt

## Overview

##### Project type and purpose
- Bolt is a compiler/interpreter project: a lightweight, embeddable programming language implemented in C, delivered as a static library plus a CLI.
- Purpose: parse, type-check, compile, and execute Bolt code in real time; expose embedding APIs for host applications; provide a small standard library; include a command-line REPL/compiler tool.

##### File structure
Top-level:
- bolt/         ← Core implementation (lexer, parser, compiler, runtime, GC, embedding API)
- boltstd/      ← Standard library modules (arrays, I/O, math, regex, etc.)
- bolt-cli/     ← Example CLI tool showing embedding and usage
- benchmarks/   ← Benchmark suites written in Bolt language
- examples/     ← .bolt source examples for language features
- tests/        ← Parser, runtime, and stdlib test cases (Bolt scripts)
- doc/          ← User guides, embedding guide, performance, standard library reference
- CMakeLists.txt, .github/   ← Build and CI configuration

##### Key insights from README
- Bolt is designed for ultra-fast compilation and execution, embed-first.
- Only depends on C standard library and libm, plus picomatch for regex.
- The CLI (bolt-cli) serves as a minimal embedding example.
- Emphasis on type safety, compactness, and easy integration.

##### Main components
a. CLI / Host Application
– bolt-cli/main.c (shows how an external C program links libbolt and invokes the API)
b. Core Bolt Library (libbolt.a/so)
– Tokenizer (bt_tokenizer.c/.h)
– Parser (bt_parser.c/.h)
– Type Checker & Inference (bt_type.c/.h)
– Compiler / Bytecode Generator (bt_compiler.c/.h)
– Runtime & VM / Evaluator (bt_context.c/.h, bt_value.c/.h, bt_object.c/.h)
– Garbage Collector (bt_gc.c/.h)
– Embedding API (bt_embedding.c/.h, bt_userdata.c/.h)
– Prelude & Standard Library Loader (bt_prelude.c/.h)
c. Bolt Standard Library Module Loader
– boltstd/*.c/.h
– picomatch submodule (regex engine)
d. Build System
– CMake orchestrates building libbolt and bolt-cli across platforms
e. Benchmarks & Tests
– .bolt scripts fed into bolt-cli or test harness via API

##### Relationships & data flow
1. Source Code (user .bolt files)
→ Tokenizer splits into tokens
→ Parser builds AST
→ Type Checker infers and annotates types
→ Compiler emits bytecode or IR
→ Runtime/Evaluator executes bytecode in a VM/Context
→ GC manages memory of allocated Bolt objects
→ Standard Library modules are loaded into the execution context
→ Host application (CLI or embedded) sends/receives data via the Embedding API
2. Host Application links against libbolt, calls initialization (bt_init), loads scripts, retrieves results.

##### Architectural patterns & design principles
- Modular C code separated by concern (lexer, parser, type, compile, runtime, GC)
- Embeddable API boundary between host and language runtime
- Static library + example CLI (single‐process, single‐threaded by default)
- Pluggable standard library modules, configurable via bt_config.h
- Minimal external dependencies, enabling portability.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Host Application / CLI
    subgraph "Host Application / CLI"
        CLI["bolt-cli/main.c"]:::orange
        CMakeCLI["CMakeLists.txt (CLI)"]:::gray
    end

    %% Core Bolt Library
    subgraph "Core Bolt Library (libbolt)"
        Entry["Entry Point (bolt/bolt.c/.h)"]:::blue
        Tokenizer["Tokenizer (bt_tokenizer.c/.h)"]:::blue
        Parser["Parser (bt_parser.c/.h)"]:::blue
        TypeChecker["Type Checker & Inference (bt_type.c/.h)"]:::blue
        Compiler["Compiler / Bytecode Generator (bt_compiler.c/.h)"]:::blue
        Runtime["Runtime / VM Context (bt_context.h)"]:::green
        Value["Value Representation (bt_value.c/.h)"]:::green
        ObjectModel["Object Model (bt_object.c/.h)"]:::green
        GC["Garbage Collector (bt_gc.c/.h)"]:::green
        EmbeddingAPI["Embedding API (bt_embedding.c/.h)"]:::orange
        UserData["User Data Integration (bt_userdata.c/.h)"]:::orange
        Prelude["Prelude & Stdlib Loader (bt_prelude.c/.h)"]:::purple
        BufferUtil["Buffer Utilities (bt_buffer.c/.h)"]:::blue
        DebugUtil["Debug Utilities (bt_debug.c/.h)"]:::blue
        ConfigDefs["Configuration Definitions (bt_config.h)"]:::gray
        OpCodes["Operation Codes (bt_op.h)"]:::gray
    end

    %% Standard Library Modules
    subgraph "Standard Library Modules"
        StdLoader["Boltstd Loader (boltstd/boltstd.c/.h)"]:::purple
        Arrays["Arrays Module (boltstd_arrays.c/.h)"]:::purple
        CoreStd["Core Module (boltstd_core.c/.h)"]:::purple
        IOStd["I/O Module (boltstd_io.c/.h)"]:::purple
        MathStd["Math Module (boltstd_math.c/.h)"]:::purple
        MetaStd["Meta Module (boltstd_meta.c/.h)"]:::purple
        RegexStd["Regex Module (boltstd_regex.c/.h)"]:::purple
        StringsStd["Strings Module (boltstd_strings.c/.h)"]:::purple
        TablesStd["Tables Module (boltstd_tables.c/.h)"]:::purple
        PicoMatch["Regex Engine (picomatch.c/.h)"]:::purple
    end

    %% Build System / CI
    subgraph "Build System / CI"
        TopCMake["CMakeLists.txt"]:::gray
        CI[".github/workflows/cmake-multi-platform.yml"]:::gray
    end

    %% Benchmarks & Tests
    subgraph "Benchmarks & Tests"
        Bench["Benchmarks (*.bolt)"]:::external
        ParserTests["Parser Tests (tests/parser/)"]:::external
        RuntimeTests["Runtime Tests (tests/runtime/)"]:::external
        StdlibTests["Stdlib Tests (tests/stdlib/)"]:::external
        GeneralTests["General Tests (tests/*.bolt)"]:::external
    end

    %% Compilation Pipeline Flow
    CLI -->|links libbolt & calls bt_init| EmbeddingAPI
    EmbeddingAPI -->|loads scripts| Tokenizer
    Tokenizer -->|tokens| Parser
    Parser -->|AST| TypeChecker
    TypeChecker -->|annotated AST| Compiler
    Compiler -->|bytecode| Runtime
    Runtime -->|execute| Value
    Runtime --> ObjectModel
    Runtime --> GC
    GC -->|manages memory| Runtime
    Runtime -->|loads stdlib| StdLoader
    StdLoader --> Arrays & CoreStd & IOStd & MathStd & MetaStd & RegexStd & StringsStd & TablesStd
    RegexStd --> PicoMatch
    Runtime -->|exposes API| EmbeddingAPI
    Bench --> CLI
    ParserTests --> Parser
    RuntimeTests --> Runtime
    StdlibTests --> StdLoader
    GeneralTests --> CLI

    TopCMake -.->|builds| Entry
    TopCMake -.->|builds| CLI
    CI -.-> TopCMake

    %% Click Events
    click CLI "https://github.com/beariish/bolt/blob/main/bolt-cli/main.c"
    click CMakeCLI "https://github.com/beariish/bolt/blob/main/bolt-cli/CMakeLists.txt"
    click Entry "https://github.com/beariish/bolt/blob/main/bolt/bolt.c"
    click Entry "https://github.com/beariish/bolt/blob/main/bolt/bolt.h"
    click Tokenizer "https://github.com/beariish/bolt/blob/main/bolt/bt_tokenizer.c"
    click Tokenizer "https://github.com/beariish/bolt/blob/main/bolt/bt_tokenizer.h"
    click Parser "https://github.com/beariish/bolt/blob/main/bolt/bt_parser.c"
    click Parser "https://github.com/beariish/bolt/blob/main/bolt/bt_parser.h"
    click TypeChecker "https://github.com/beariish/bolt/blob/main/bolt/bt_type.c"
    click TypeChecker "https://github.com/beariish/bolt/blob/main/bolt/bt_type.h"
    click Compiler "https://github.com/beariish/bolt/blob/main/bolt/bt_compiler.c"
    click Compiler "https://github.com/beariish/bolt/blob/main/bolt/bt_compiler.h"
    click Runtime "https://github.com/beariish/bolt/blob/main/bolt/bt_context.h"
    click Value "https://github.com/beariish/bolt/blob/main/bolt/bt_value.c"
    click Value "https://github.com/beariish/bolt/blob/main/bolt/bt_value.h"
    click ObjectModel "https://github.com/beariish/bolt/blob/main/bolt/bt_object.c"
    click ObjectModel "https://github.com/beariish/bolt/blob/main/bolt/bt_object.h"
    click GC "https://github.com/beariish/bolt/blob/main/bolt/bt_gc.c"
    click GC "https://github.com/beariish/bolt/blob/main/bolt/bt_gc.h"
    click EmbeddingAPI "https://github.com/beariish/bolt/blob/main/bolt/bt_embedding.c"
    click EmbeddingAPI "https://github.com/beariish/bolt/blob/main/bolt/bt_embedding.h"
    click UserData "https://github.com/beariish/bolt/blob/main/bolt/bt_userdata.c"
    click UserData "https://github.com/beariish/bolt/blob/main/bolt/bt_userdata.h"
    click Prelude "https://github.com/beariish/bolt/blob/main/bolt/bt_prelude.c"
    click Prelude "https://github.com/beariish/bolt/blob/main/bolt/bt_prelude.h"
    click BufferUtil "https://github.com/beariish/bolt/blob/main/bolt/bt_buffer.c"
    click BufferUtil "https://github.com/beariish/bolt/blob/main/bolt/bt_buffer.h"
    click DebugUtil "https://github.com/beariish/bolt/blob/main/bolt/bt_debug.c"
    click DebugUtil "https://github.com/beariish/bolt/blob/main/bolt/bt_debug.h"
    click ConfigDefs "https://github.com/beariish/bolt/blob/main/bolt/bt_config.h"
    click OpCodes "https://github.com/beariish/bolt/blob/main/bolt/bt_op.h"
    click StdLoader "https://github.com/beariish/bolt/blob/main/bolt/boltstd/boltstd.c"
    click StdLoader "https://github.com/beariish/bolt/blob/main/bolt/boltstd/boltstd.h"
    click Arrays "https://github.com/beariish/bolt/blob/main/bolt/boltstd/boltstd_arrays.c"
    click Arrays "https://github.com/beariish/bolt/blob/main/bolt/boltstd/boltstd_arrays.h"
    click CoreStd "https://github.com/beariish/bolt/blob/main/bolt/boltstd/boltstd_core.c"
    click CoreStd "https://github.com/beariish/bolt/blob/main/bolt/boltstd/boltstd_core.h"
    click IOStd "https://github.com/beariish/bolt/blob/main/bolt/boltstd/boltstd_io.c"
    click IOStd "https://github.com/beariish/bolt/blob/main/bolt/boltstd/boltstd_io.h"
    click MathStd "https://github.com/beariish/bolt/blob/main/bolt/boltstd/boltstd_math.c"
    click MathStd "https://github.com/beariish/bolt/blob/main/bolt/boltstd/boltstd_math.h"
    click MetaStd "https://github.com/beariish/bolt/blob/main/bolt/boltstd/boltstd_meta.c"
    click MetaStd "https://github.com/beariish/bolt/blob/main/bolt/boltstd/boltstd_meta.h"
    click RegexStd "https://github.com/beariish/bolt/blob/main/bolt/boltstd/boltstd_regex.c"
    click RegexStd "https://github.com/beariish/bolt/blob/main/bolt/boltstd/boltstd_regex.h"
    click StringsStd "https://github.com/beariish/bolt/blob/main/bolt/boltstd/boltstd_strings.c"
    click StringsStd "https://github.com/beariish/bolt/blob/main/bolt/boltstd/boltstd_strings.h"
    click TablesStd "https://github.com/beariish/bolt/blob/main/bolt/boltstd/boltstd_tables.c"
    click TablesStd "https://github.com/beariish/bolt/blob/main/bolt/boltstd/boltstd_tables.h"
    click PicoMatch "https://github.com/beariish/bolt/blob/main/bolt/boltstd/picomatch/picomatch.c"
    click PicoMatch "https://github.com/beariish/bolt/blob/main/bolt/boltstd/picomatch/picomatch.h"
    click TopCMake "https://github.com/beariish/bolt/blob/main/CMakeLists.txt"
    click CI "https://github.com/beariish/bolt/blob/main/.github/workflows/cmake-multi-platform.yml"

    %% Styles
    classDef blue fill:#E0F7FA,stroke:#0288D1,color:#01579B
    classDef green fill:#E8F5E9,stroke:#43A047,color:#1B5E20
    classDef orange fill:#FFE0B2,stroke:#FB8C00,color:#E65100
    classDef purple fill:#E1BEE7,stroke:#8E24AA,color:#4A148C
    classDef gray fill:#CFD8DC,stroke:#546E7A,color:#263238
    classDef external fill:#F5F5F5,stroke:#BDBDBD,color:#424242
```
