# eaddrinuse-98/vertex architecture

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

- Interactive diagram: https://gitdiagram.com/eaddrinuse-98/vertex
- Repository: https://github.com/eaddrinuse-98/vertex

## Overview

Vertex is a statically typed language implementation that compiles source into bytecode and executes it in a virtual machine. Its principal workflow is source tokenization, parsing into compilable program nodes, bytecode generation and optimization, then bytecode loading and execution. The tree also shows object linking, bytecode persistence, compile-time checking, built-in macros, and a separate runtime library. The sampled code confirms lexer, parser, compile-context, and VM behavior; orchestration links among unsampled modules are omitted where their callers cannot be verified.

Main entry points: [`src/backend/compiler/instructions.rs`](https://github.com/eaddrinuse-98/vertex/blob/main/src/backend/compiler/instructions.rs) (Instructions), [`src/backend/ast/parser/parser_trait.rs`](https://github.com/eaddrinuse-98/vertex/blob/main/src/backend/ast/parser/parser_trait.rs) (Parser), [`src/runtime/virtual_machine/vm.rs`](https://github.com/eaddrinuse-98/vertex/blob/main/src/runtime/virtual_machine/vm.rs) (Virtual machine), [`src/backend/lexer/tokens.rs`](https://github.com/eaddrinuse-98/vertex/blob/main/src/backend/lexer/tokens.rs) (Token definitions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Source Frontend"]
  node_lexer["Lexer<br/>[tokenizer.rs]"]
  node_tokens["Token definitions<br/>[tokens.rs]"]
  node_parser["Parser<br/>[parser_trait.rs]"]
  node_ast["Program AST<br/>[program_node.rs]"]
  node_errors["Diagnostics<br/>[mod.rs]"]
end

subgraph group_compile["Compilation"]
  node_compiler["Bytecode compiler<br/>[mod.rs]"]
  node_typecheck["Compile-time checks<br/>[mod.rs]"]
  node_optimize["Optimizer<br/>[optimize.rs]"]
  node_instructions["Instructions<br/>[instructions.rs]"]
  node_linker["Object linker<br/>[link.rs]"]
  node_object["Object files<br/>[obj_file.rs]"]
  node_bytecode_io["Bytecode persistence<br/>[mod.rs]"]
end

subgraph group_execution["Execution"]
  node_runner["VM runner<br/>[mod.rs]"]
  node_loader["Bytecode loader<br/>[pre_parsing.rs]"]
  node_vm["Virtual machine<br/>[vm.rs]"]
  node_values["Values and variables<br/>[value.rs]"]
end

subgraph group_language["Language Support"]
  node_macros["Built-in macros<br/>[mod.rs]"]
  node_runtime_lib["Runtime library<br/>[lib.rs]"]
end

node_user(("Language user"))
node_compiler_cli["Compiler CLI<br/>[vertexC.rs]"]

node_user -->|"invokes"| node_compiler_cli
node_lexer -->|"creates"| node_tokens
node_parser -->|"consumes"| node_tokens
node_parser -->|"builds"| node_ast
node_compiler -->|"emits"| node_instructions
node_optimize -->|"rewrites"| node_instructions
node_linker -->|"patches"| node_object
node_bytecode_io -->|"serializes"| node_instructions
node_loader -->|"loads"| node_instructions
node_runner -->|"runs"| node_vm
node_vm -->|"operates on"| node_values

click node_compiler_cli "https://github.com/eaddrinuse-98/vertex/blob/main/src/bin/vertexC.rs"
click node_lexer "https://github.com/eaddrinuse-98/vertex/blob/main/src/backend/lexer/tokenizer.rs"
click node_tokens "https://github.com/eaddrinuse-98/vertex/blob/main/src/backend/lexer/tokens.rs"
click node_parser "https://github.com/eaddrinuse-98/vertex/blob/main/src/backend/ast/parser/parser_trait.rs"
click node_ast "https://github.com/eaddrinuse-98/vertex/blob/main/src/backend/ast/nodes/program_node.rs"
click node_errors "https://github.com/eaddrinuse-98/vertex/blob/main/src/backend/errors/mod.rs"
click node_compiler "https://github.com/eaddrinuse-98/vertex/blob/main/src/backend/compiler/mod.rs"
click node_typecheck "https://github.com/eaddrinuse-98/vertex/blob/main/src/backend/compiler/comptime_variable_checker/mod.rs"
click node_optimize "https://github.com/eaddrinuse-98/vertex/blob/main/src/backend/compiler/optimization/optimize.rs"
click node_instructions "https://github.com/eaddrinuse-98/vertex/blob/main/src/backend/compiler/instructions.rs"
click node_linker "https://github.com/eaddrinuse-98/vertex/blob/main/src/backend/linker/link.rs"
click node_object "https://github.com/eaddrinuse-98/vertex/blob/main/src/backend/linker/obj_file.rs"
click node_bytecode_io "https://github.com/eaddrinuse-98/vertex/blob/main/src/backend/saving_bytes/mod.rs"
click node_runner "https://github.com/eaddrinuse-98/vertex/blob/main/src/runtime/runner/mod.rs"
click node_loader "https://github.com/eaddrinuse-98/vertex/blob/main/src/runtime/virtual_machine/pre_parsing.rs"
click node_vm "https://github.com/eaddrinuse-98/vertex/blob/main/src/runtime/virtual_machine/vm.rs"
click node_values "https://github.com/eaddrinuse-98/vertex/blob/main/src/runtime/virtual_machine/value.rs"
click node_macros "https://github.com/eaddrinuse-98/vertex/blob/main/src/backend/buildin_macros/mod.rs"
click node_runtime_lib "https://github.com/eaddrinuse-98/vertex/blob/main/src/runtime_lib/src/lib.rs"

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_tokens,node_parser,node_ast,node_errors,node_user toneBlue
class node_compiler,node_typecheck,node_optimize,node_instructions,node_linker,node_object,node_bytecode_io toneAmber
class node_runner,node_loader,node_vm,node_values toneMint
class node_macros,node_runtime_lib toneRose
class node_compiler_cli toneTeal
```

## Components

### Source Frontend

- [Lexer](https://github.com/eaddrinuse-98/vertex/blob/main/src/backend/lexer/tokenizer.rs): `src/backend/lexer/tokenizer.rs`
- [Token definitions](https://github.com/eaddrinuse-98/vertex/blob/main/src/backend/lexer/tokens.rs): `src/backend/lexer/tokens.rs`
- [Parser](https://github.com/eaddrinuse-98/vertex/blob/main/src/backend/ast/parser/parser_trait.rs): `src/backend/ast/parser/parser_trait.rs`
- [Program AST](https://github.com/eaddrinuse-98/vertex/blob/main/src/backend/ast/nodes/program_node.rs): `src/backend/ast/nodes/program_node.rs`
- [Diagnostics](https://github.com/eaddrinuse-98/vertex/blob/main/src/backend/errors/mod.rs): `src/backend/errors/mod.rs`

### Compilation

- [Bytecode compiler](https://github.com/eaddrinuse-98/vertex/blob/main/src/backend/compiler/mod.rs): `src/backend/compiler/mod.rs`
- [Compile-time checks](https://github.com/eaddrinuse-98/vertex/blob/main/src/backend/compiler/comptime_variable_checker/mod.rs): `src/backend/compiler/comptime_variable_checker/mod.rs`
- [Optimizer](https://github.com/eaddrinuse-98/vertex/blob/main/src/backend/compiler/optimization/optimize.rs): `src/backend/compiler/optimization/optimize.rs`
- [Instructions](https://github.com/eaddrinuse-98/vertex/blob/main/src/backend/compiler/instructions.rs): `src/backend/compiler/instructions.rs`
- [Object linker](https://github.com/eaddrinuse-98/vertex/blob/main/src/backend/linker/link.rs): `src/backend/linker/link.rs`
- [Object files](https://github.com/eaddrinuse-98/vertex/blob/main/src/backend/linker/obj_file.rs): `src/backend/linker/obj_file.rs`
- [Bytecode persistence](https://github.com/eaddrinuse-98/vertex/blob/main/src/backend/saving_bytes/mod.rs): `src/backend/saving_bytes/mod.rs`

### Execution

- [VM runner](https://github.com/eaddrinuse-98/vertex/blob/main/src/runtime/runner/mod.rs): `src/runtime/runner/mod.rs`
- [Bytecode loader](https://github.com/eaddrinuse-98/vertex/blob/main/src/runtime/virtual_machine/pre_parsing.rs): `src/runtime/virtual_machine/pre_parsing.rs`
- [Virtual machine](https://github.com/eaddrinuse-98/vertex/blob/main/src/runtime/virtual_machine/vm.rs): `src/runtime/virtual_machine/vm.rs`
- [Values and variables](https://github.com/eaddrinuse-98/vertex/blob/main/src/runtime/virtual_machine/value.rs): `src/runtime/virtual_machine/value.rs`

### Language Support

- [Built-in macros](https://github.com/eaddrinuse-98/vertex/blob/main/src/backend/buildin_macros/mod.rs): `src/backend/buildin_macros/mod.rs`
- [Runtime library](https://github.com/eaddrinuse-98/vertex/blob/main/src/runtime_lib/src/lib.rs): `src/runtime_lib/src/lib.rs`

### Other components

- **Language user**
- [Compiler CLI](https://github.com/eaddrinuse-98/vertex/blob/main/src/bin/vertexC.rs): `src/bin/vertexC.rs`

## Connections

- Language user → Compiler CLI: invokes
- Lexer → Token definitions: creates
- Parser → Token definitions: consumes
- Parser → Program AST: builds
- Bytecode compiler → Instructions: emits
- Optimizer → Instructions: rewrites
- Object linker → Object files: patches
- Bytecode persistence → Instructions: serializes
- Bytecode loader → Instructions: loads
- VM runner → Virtual machine: runs
- Virtual machine → Values and variables: operates on