# jdrc6000/forge architecture

> Architecture diagram of the GitHub repository jdrc6000/forge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jdrc6000/forge
- Repository: https://github.com/jdrc6000/forge

## Overview

Forge is a Python-based educational compiler and virtual machine. A source file or source string enters through the runner, is tokenized and parsed, checked semantically, optimized, lowered to IR, analyzed as a control-flow graph, register-allocated, and executed by the VM. The README also documents builtins and optimization passes; the tree and excerpts support separate runtime support for methods and module loading. Some pipeline calls are omitted from the excerpts, so those links rely on the documented pipeline rather than sampled call sites.

Main entry points: [`main.py`](https://github.com/jdrc6000/forge/blob/main/main.py) (Compile runner), [`bootstrap/runtime/vm.py`](https://github.com/jdrc6000/forge/blob/main/bootstrap/runtime/vm.py) (Virtual machine), [`bootstrap/semantic/analyser.py`](https://github.com/jdrc6000/forge/blob/main/bootstrap/semantic/analyser.py) (Semantic analysis), [`bootstrap/frontend/parser.py`](https://github.com/jdrc6000/forge/blob/main/bootstrap/frontend/parser.py) (Parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_front["Frontend"]
  node_lexer["Lexer<br/>[lexer.py]"]
  node_parser["Parser<br/>[parser.py]"]
  node_ast["AST nodes<br/>[ast_nodes.py]"]
  node_analyser["Semantic analysis<br/>[analyser.py]"]
  node_symbols[("Symbol table<br/>[symbol_table.py]")]
  node_diagnostics["Diagnostics<br/>[exceptions.py]"]
end

subgraph group_compile["Compiler"]
  node_optimiser["AST optimizer<br/>[optimiser.py]"]
  node_passes["Optimization passes<br/>[passes.py]"]
  node_irgen["IR generator<br/>[generator.py]"]
  node_ir["Instruction IR<br/>[ir.py]"]
  node_cfg["CFG builder<br/>[cfg_builder.py]"]
  node_liveness["CFG analysis<br/>[liveness.py]"]
  node_regalloc["Register allocator<br/>[regalloc.py]"]
end

subgraph group_runtime["Runtime"]
  node_vm["Virtual machine<br/>[vm.py]"]
  node_builtins["Builtin functions"]
  node_methods["Member methods<br/>[methods.py]"]
end

node_user(("Program author"))
node_runner["Compile runner<br/>[main.py]"]
node_module_files["Module source files"]
node_program_output(("Program output"))

node_user -->|"provides source"| node_runner
node_runner -->|"tokenizes"| node_lexer
node_lexer -->|"emits tokens"| node_parser
node_parser -->|"builds tree"| node_ast
node_runner -->|"checks tree"| node_analyser
node_analyser -->|"consults scopes"| node_symbols
node_runner -->|"optimizes tree"| node_optimiser
node_optimiser -->|"runs passes"| node_passes
node_runner -->|"lowers tree"| node_irgen
node_irgen -->|"emits instructions"| node_ir
node_runner -->|"builds CFG"| node_cfg
node_cfg -->|"analyzes blocks"| node_liveness
node_runner -->|"prunes and analyzes"| node_liveness
node_runner -->|"allocates registers"| node_regalloc
node_runner -->|"loads and runs code"| node_vm
node_vm -->|"dispatches builtins"| node_builtins
node_vm -->|"resolves members"| node_methods
node_analyser -->|"reads imports"| node_module_files
node_vm -->|"executes program"| node_program_output
node_parser -->|"raises parse errors"| node_diagnostics
node_analyser -->|"raises compile errors"| node_diagnostics
node_vm -->|"reports runtime errors"| node_diagnostics

click node_runner "https://github.com/jdrc6000/forge/blob/main/main.py"
click node_lexer "https://github.com/jdrc6000/forge/blob/main/bootstrap/frontend/lexer.py"
click node_parser "https://github.com/jdrc6000/forge/blob/main/bootstrap/frontend/parser.py"
click node_ast "https://github.com/jdrc6000/forge/blob/main/bootstrap/frontend/ast_nodes.py"
click node_analyser "https://github.com/jdrc6000/forge/blob/main/bootstrap/semantic/analyser.py"
click node_symbols "https://github.com/jdrc6000/forge/blob/main/bootstrap/semantic/symbol_table.py"
click node_diagnostics "https://github.com/jdrc6000/forge/blob/main/bootstrap/exceptions.py"
click node_optimiser "https://github.com/jdrc6000/forge/blob/main/bootstrap/optimiser/optimiser.py"
click node_passes "https://github.com/jdrc6000/forge/blob/main/bootstrap/optimiser/passes.py"
click node_irgen "https://github.com/jdrc6000/forge/blob/main/bootstrap/ir/generator.py"
click node_ir "https://github.com/jdrc6000/forge/blob/main/bootstrap/ir/ir.py"
click node_cfg "https://github.com/jdrc6000/forge/blob/main/bootstrap/ir/cfg_builder.py"
click node_liveness "https://github.com/jdrc6000/forge/blob/main/bootstrap/ir/liveness.py"
click node_regalloc "https://github.com/jdrc6000/forge/blob/main/bootstrap/runtime/regalloc.py"
click node_vm "https://github.com/jdrc6000/forge/blob/main/bootstrap/runtime/vm.py"
click node_builtins "https://github.com/jdrc6000/forge/blob/main/bootstrap/runtime/builtins_registry.py"
click node_methods "https://github.com/jdrc6000/forge/blob/main/bootstrap/runtime/methods.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_lexer,node_parser,node_ast,node_analyser,node_symbols,node_diagnostics toneBlue
class node_optimiser,node_passes,node_irgen,node_ir,node_cfg,node_liveness,node_regalloc toneAmber
class node_vm,node_builtins,node_methods toneMint
class node_user,node_module_files,node_program_output toneIndigo
class node_runner toneTeal
```

## Components

### Frontend

- [Lexer](https://github.com/jdrc6000/forge/blob/main/bootstrap/frontend/lexer.py): `bootstrap/frontend/lexer.py`
- [Parser](https://github.com/jdrc6000/forge/blob/main/bootstrap/frontend/parser.py): `bootstrap/frontend/parser.py`
- [AST nodes](https://github.com/jdrc6000/forge/blob/main/bootstrap/frontend/ast_nodes.py): `bootstrap/frontend/ast_nodes.py`
- [Semantic analysis](https://github.com/jdrc6000/forge/blob/main/bootstrap/semantic/analyser.py): `bootstrap/semantic/analyser.py`
- [Symbol table](https://github.com/jdrc6000/forge/blob/main/bootstrap/semantic/symbol_table.py): `bootstrap/semantic/symbol_table.py`
- [Diagnostics](https://github.com/jdrc6000/forge/blob/main/bootstrap/exceptions.py): `bootstrap/exceptions.py`

### Compiler

- [AST optimizer](https://github.com/jdrc6000/forge/blob/main/bootstrap/optimiser/optimiser.py): `bootstrap/optimiser/optimiser.py`
- [Optimization passes](https://github.com/jdrc6000/forge/blob/main/bootstrap/optimiser/passes.py): `bootstrap/optimiser/passes.py`
- [IR generator](https://github.com/jdrc6000/forge/blob/main/bootstrap/ir/generator.py): `bootstrap/ir/generator.py`
- [Instruction IR](https://github.com/jdrc6000/forge/blob/main/bootstrap/ir/ir.py): `bootstrap/ir/ir.py`
- [CFG builder](https://github.com/jdrc6000/forge/blob/main/bootstrap/ir/cfg_builder.py): `bootstrap/ir/cfg_builder.py`
- [CFG analysis](https://github.com/jdrc6000/forge/blob/main/bootstrap/ir/liveness.py): `bootstrap/ir/liveness.py`
- [Register allocator](https://github.com/jdrc6000/forge/blob/main/bootstrap/runtime/regalloc.py): `bootstrap/runtime/regalloc.py`

### Runtime

- [Virtual machine](https://github.com/jdrc6000/forge/blob/main/bootstrap/runtime/vm.py): `bootstrap/runtime/vm.py`
- [Builtin functions](https://github.com/jdrc6000/forge/blob/main/bootstrap/runtime/builtins_registry.py): `bootstrap/runtime/builtins_registry.py`
- [Member methods](https://github.com/jdrc6000/forge/blob/main/bootstrap/runtime/methods.py): `bootstrap/runtime/methods.py`

### Other components

- **Program author**
- [Compile runner](https://github.com/jdrc6000/forge/blob/main/main.py): `main.py`
- **Module source files**
- **Program output**

## Connections

- Program author → Compile runner: provides source
- Compile runner → Lexer: tokenizes
- Lexer → Parser: emits tokens
- Parser → AST nodes: builds tree
- Compile runner → Semantic analysis: checks tree
- Semantic analysis → Symbol table: consults scopes
- Compile runner → AST optimizer: optimizes tree
- AST optimizer → Optimization passes: runs passes
- Compile runner → IR generator: lowers tree
- IR generator → Instruction IR: emits instructions
- Compile runner → CFG builder: builds CFG
- CFG builder → CFG analysis: analyzes blocks
- Compile runner → CFG analysis: prunes and analyzes
- Compile runner → Register allocator: allocates registers
- Compile runner → Virtual machine: loads and runs code
- Virtual machine → Builtin functions: dispatches builtins
- Virtual machine → Member methods: resolves members
- Semantic analysis → Module source files: reads imports
- Virtual machine → Program output: executes program
- Parser → Diagnostics: raises parse errors
- Semantic analysis → Diagnostics: raises compile errors
- Virtual machine → Diagnostics: reports runtime errors