# mlochbaum/bqn architecture

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

- Interactive diagram: https://gitdiagram.com/mlochbaum/bqn
- Repository: https://github.com/mlochbaum/bqn

## Overview

##### Core Language Components
- Compiler/Interpreter System
- Virtual Machine (VM)
- Runtime System
- Standard Library

##### Implementation Architecture

a) Frontend Layer:
- Documentation System (docs/)
- REPL Interface (online and offline)
- Editor Support (editors/)
- Custom Font Rendering

b) Core Processing Layer:
- Parser/Lexer (spec/grammar.md, spec/token.md)
- Compiler Pipeline (implementation/compile/)
- Bytecode Generator
- Virtual Machine (implementation/vm.md)

c) Runtime Layer:
- Primitive Operations (implementation/primitive/)
- System Functions
- Foreign Function Interface (FFI)
- Type System (spec/types.md)

d) Testing/Development Infrastructure:
- Test Framework (test/)
- Benchmarking System (implementation/bootbench.md)
- Self-hosted Compiler (src/)

Use these visual elements:

##### Component Representation
- Use rectangles for major system components
- Use rounded rectangles for interfaces/APIs
- Use hexagons for processing units

##### Connection Types
- Double lines: Data flow

Key Relationships to Highlight:

##### Compilation Pipeline
Source Code → Parser → AST → Bytecode → VM Execution

##### Runtime Integration
VM ↔ Primitive Operations ↔ System Functions ↔ FFI

##### Development Workflow
Source Files → Self-hosted Compiler → Tests → Documentation

##### Frontend Integration
REPL → VM → Runtime System
Editor Support → Parser → Core Language

Special considerations:

##### Demonstrate the integration with external systems via FFI

- Version/status indicators
- Implementation-specific details

Level of Detail:
- Keep high-level architecture clear while showing important subsystems
- Major data flows and transformations
- System boundaries and external interfaces
- Maintain clarity of the self-hosted nature of the implementation

## Diagram (Mermaid)

```mermaid
graph TB
    %% Style definitions
    classDef frontend fill:#90EE90,stroke:#333,stroke-width:2px
    classDef core fill:#87CEEB,stroke:#333,stroke-width:2px
    classDef runtime fill:#FFA500,stroke:#333,stroke-width:2px
    classDef development fill:#DDA0DD,stroke:#333,stroke-width:2px
    classDef storage fill:#A9A9A9,stroke:#333,stroke-width:2px

    subgraph Frontend
        REPL["REPL Interface"]:::frontend
        DOC["Documentation System"]:::frontend
        EDIT["Editor Support"]:::frontend
        FONT["Font Rendering"]:::frontend
    end

    subgraph CoreProcessing
        PARSE["Parser/Grammar"]:::core
        COMP["Compiler System"]:::core
        BYTEGEN["Bytecode Generator"]:::core
        VM["Virtual Machine"]:::core
    end

    subgraph Runtime
        PRIM["Primitive Operations"]:::runtime
        SYSFN["System Functions"]:::runtime
        FFI["Foreign Function Interface"]:::runtime
        TYPE["Type System"]:::runtime
        STDLIB["Standard Library"]:::runtime
        RT["Runtime System"]:::runtime
    end

    subgraph Development
        TEST["Test Framework"]:::development
        BENCH["Benchmarking System"]:::development
        SELF["Self-hosted Compiler"]:::development
    end

    %% Relationships
    REPL --> VM
    EDIT --> PARSE
    PARSE --> COMP
    COMP --> BYTEGEN
    BYTEGEN --> VM
    VM --> PRIM
    PRIM --> SYSFN
    SYSFN --> FFI
    VM --> RT
    RT --> STDLIB
    TYPE --> COMP
    TYPE --> VM
    
    TEST --> COMP
    BENCH --> VM
    SELF --> COMP

    %% Click events
    click VM "https://github.com/mlochbaum/BQN/blob/master/implementation/vm.md"
    click COMP "https://github.com/mlochbaum/BQN/tree/master/implementation/compile/"
    click DOC "https://github.com/mlochbaum/BQN/tree/master/doc/"
    click EDIT "https://github.com/mlochbaum/BQN/tree/master/editors/"
    click PRIM "https://github.com/mlochbaum/BQN/tree/master/implementation/primitive/"
    click TEST "https://github.com/mlochbaum/BQN/tree/master/test/"
    click FFI "https://github.com/mlochbaum/BQN/blob/master/doc/ffi.md"
    click TYPE "https://github.com/mlochbaum/BQN/blob/master/spec/types.md"
    click PARSE "https://github.com/mlochbaum/BQN/blob/master/spec/grammar.md"
    click FONT "https://github.com/mlochbaum/BQN/tree/master/fonts/"
    click REPL "https://github.com/mlochbaum/BQN/blob/master/docs/repl.js"
    click BENCH "https://github.com/mlochbaum/BQN/blob/master/implementation/bootbench.md"
    click SELF "https://github.com/mlochbaum/BQN/tree/master/src/bootstrap/"
    click RT "https://github.com/mlochbaum/BQN/blob/master/rt.bqn"
    click STDLIB "https://github.com/mlochbaum/BQN/blob/master/spec/primitive.md"

    %% Legend
    subgraph Legend
        L1["Frontend Components"]:::frontend
        L2["Core Components"]:::core
        L3["Runtime Components"]:::runtime
        L4["Development Tools"]:::development
    end
```
