# ak47andrew/virtual-console architecture

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

- Interactive diagram: https://gitdiagram.com/ak47andrew/virtual-console
- Repository: https://github.com/ak47andrew/virtual-console

## Overview

#### Purpose and workspace shape
This is a Rust workspace for a VEA virtual-machine/cartridge ecosystem: assemble VEA source and assets into cartridges, run them in an emulator, launch workflows, and provide editor/language tooling. The top-level workspace is defined by `Cargo.toml`; shared VM and cartridge contracts live in `src/shared/`.

#### Executable entry points
- Compiler CLI: `src/compiler/src/main.rs`, with orchestration in `src/compiler/src/entry.rs`.
- Emulator/runtime executable: `src/runtime/src/main.rs`.
- Launcher executable, including a non-UI mode: `src/launcher/src/main.rs`, `src/launcher/src/nonui.rs`.
- Language-server executable: `src/lsp/src/main.rs`.
- Flowchart generator executable: `src/flowchart-gen/src/main.rs`.

These are separate crates under `src/`, coordinated through the workspace rather than a single server or web application.

#### Shared VM and cartridge contract
`src/shared/` is the architectural boundary between producer-side tooling and execution-side runtime. It defines cartridge representation and loading-related primitives in `src/shared/src/cartridge.rs`, cartridge manifest structures in `src/shared/src/manifest.rs`, and VM instruction/operand/register definitions in `src/shared/src/opcodes.rs`, `src/shared/src/operand_types.rs`, and `src/shared/src/registers.rs`. Compiler, runtime, and tooling should depend on these definitions rather than duplicate instruction encoding or cartridge semantics.

#### Compilation pipeline
The compiler accepts VEA assembly plus cartridge resources, parses and validates instructions, then emits the shared cartridge format. Assembly parsing and operand validation are concentrated in `src/compiler/src/vea/parsing.rs` and `src/compiler/src/vea/operand_checking.rs`; compiler dispatch/error handling is in `src/compiler/src/entry.rs` and `src/compiler/src/errors.rs`. Asset compilation is a distinct stage for images and palettes under `src/compiler/src/images/mod.rs` and `src/compiler/src/palette/mod.rs`. Example cartridge inputs establish the expected boundary: `examples/example_cartridge/source.vea`, `examples/example_cartridge/manifest.toml`, and `examples/example_cartridge/palette.pal`.

#### Runtime execution and debugging
The runtime loads a compiled cartridge and executes its VM program. `src/runtime/src/emulator.rs` owns instruction execution/control flow, while `src/runtime/src/memory.rs` represents VM memory behavior and `src/runtime/src/debugger.rs` supplies debugging integration. Its primary dependency boundary is the shared cartridge, opcode, register, and memory constants model in `src/shared/src/`.

#### Developer tooling and documentation
The LSP packages opcode documentation from `src/lsp/opcodes/` during its build (`src/lsp/build.rs`) and serves language functionality from `src/lsp/src/main.rs`; it should remain aligned with shared opcode definitions. `src/flowchart-gen/src/graph.rs` provides a separate analysis/visualization path over program control flow. The mdBook documentation under `docs/src/` describes the language and VM model, especially `docs/src/assembler.md`, `docs/src/memory.md`, and `docs/src/opcodes.md`.

Main entry points: [`src/compiler/src/entry.rs`](https://github.com/ak47andrew/virtual-console/blob/main/src/compiler/src/entry.rs) (Compile orchestration), [`src/compiler/src/main.rs`](https://github.com/ak47andrew/virtual-console/blob/main/src/compiler/src/main.rs) (Compiler CLI), [`src/shared/src/opcodes.rs`](https://github.com/ak47andrew/virtual-console/blob/main/src/shared/src/opcodes.rs) (VM ISA contracts), [`src/runtime/src/emulator.rs`](https://github.com/ak47andrew/virtual-console/blob/main/src/runtime/src/emulator.rs) (VM emulator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Cartridge Inputs"]
  node_source["VEA assembly<br/>source input<br/>[source.vea]"]
  node_manifest["Cartridge manifest<br/>metadata input<br/>[manifest.toml]"]
  node_palette["Palette asset<br/>asset input<br/>[palette.pal]"]
end

subgraph group_compiler["Compiler"]
  node_compiler_cli["Compiler CLI<br/>Rust executable<br/>[main.rs]"]
  node_compiler_entry["Compile orchestration<br/>compiler dispatch<br/>[entry.rs]"]
  node_assembly_parser["Assembly parser<br/>[parsing.rs]"]
  node_operand_validation["Operand validation<br/>validator"]
  node_asset_compiler["Image &amp; palette compilation<br/>asset pipeline<br/>[mod.rs]"]
end

subgraph group_shared["Shared Contract"]
  node_cartridge_model["Cartridge format<br/>shared contract<br/>[cartridge.rs]"]
  node_manifest_model["Manifest contract<br/>shared contract<br/>[manifest.rs]"]
  node_vm_isa["VM ISA contracts<br/>instruction model<br/>[opcodes.rs]"]
end

subgraph group_runtime["Execution"]
  node_runtime_cli["Runtime executable<br/>Rust executable<br/>[main.rs]"]
  node_emulator["VM emulator<br/>execution engine<br/>[emulator.rs]"]
  node_vm_memory["VM memory<br/>memory model<br/>[memory.rs]"]
  node_debugger["Debugger<br/>debug integration<br/>[debugger.rs]"]
  node_launcher["Launcher<br/>Rust executable<br/>[main.rs]"]
end

subgraph group_tooling["Tooling &amp; Docs"]
  node_lsp["Language server<br/>Rust executable<br/>[main.rs]"]
  node_opcode_docs["Opcode documentation package<br/>build input"]
  node_flowchart["Flowchart generator<br/>Rust executable<br/>[main.rs]"]
  node_flow_graph["Control-flow analysis<br/>graph analysis<br/>[graph.rs]"]
  node_docs["VM &amp; assembler docs<br/>mdBook documentation"]
end

node_source -->|"compile"| node_compiler_cli
node_manifest -->|"package metadata"| node_compiler_cli
node_palette -->|"asset"| node_compiler_cli
node_compiler_cli -->|"invokes"| node_compiler_entry
node_compiler_entry -->|"parses"| node_assembly_parser
node_assembly_parser -->|"validates operands"| node_operand_validation
node_compiler_entry -->|"compiles assets"| node_asset_compiler
node_compiler_entry -->|"emits"| node_cartridge_model
node_compiler_entry -->|"uses"| node_manifest_model
node_operand_validation -->|"checks against"| node_vm_isa
node_cartridge_model -->|"compiled cartridge"| node_runtime_cli
node_runtime_cli -->|"runs"| node_emulator
node_emulator -->|"reads and writes"| node_vm_memory
node_emulator -->|"debug hooks"| node_debugger
node_emulator -->|"executes"| node_vm_isa
node_launcher -->|"launches workflow"| node_compiler_cli
node_launcher -->|"launches workflow"| node_runtime_cli
node_lsp -->|"packages at build"| node_opcode_docs
node_lsp -->|"aligns with"| node_vm_isa
node_flowchart -->|"generates"| node_flow_graph
node_flow_graph -->|"interprets control flow"| node_vm_isa
node_docs -.->|"documents"| node_vm_isa
node_docs -.->|"documents"| node_cartridge_model

click node_source "https://github.com/ak47andrew/virtual-console/blob/main/examples/example_cartridge/source.vea"
click node_manifest "https://github.com/ak47andrew/virtual-console/blob/main/examples/example_cartridge/manifest.toml"
click node_palette "https://github.com/ak47andrew/virtual-console/blob/main/examples/example_cartridge/palette.pal"
click node_compiler_cli "https://github.com/ak47andrew/virtual-console/blob/main/src/compiler/src/main.rs"
click node_compiler_entry "https://github.com/ak47andrew/virtual-console/blob/main/src/compiler/src/entry.rs"
click node_assembly_parser "https://github.com/ak47andrew/virtual-console/blob/main/src/compiler/src/vea/parsing.rs"
click node_operand_validation "https://github.com/ak47andrew/virtual-console/blob/main/src/compiler/src/vea/operand_checking.rs"
click node_asset_compiler "https://github.com/ak47andrew/virtual-console/blob/main/src/compiler/src/images/mod.rs"
click node_cartridge_model "https://github.com/ak47andrew/virtual-console/blob/main/src/shared/src/cartridge.rs"
click node_manifest_model "https://github.com/ak47andrew/virtual-console/blob/main/src/shared/src/manifest.rs"
click node_vm_isa "https://github.com/ak47andrew/virtual-console/blob/main/src/shared/src/opcodes.rs"
click node_runtime_cli "https://github.com/ak47andrew/virtual-console/blob/main/src/runtime/src/main.rs"
click node_emulator "https://github.com/ak47andrew/virtual-console/blob/main/src/runtime/src/emulator.rs"
click node_vm_memory "https://github.com/ak47andrew/virtual-console/blob/main/src/runtime/src/memory.rs"
click node_debugger "https://github.com/ak47andrew/virtual-console/blob/main/src/runtime/src/debugger.rs"
click node_launcher "https://github.com/ak47andrew/virtual-console/blob/main/src/launcher/src/main.rs"
click node_lsp "https://github.com/ak47andrew/virtual-console/blob/main/src/lsp/src/main.rs"
click node_flowchart "https://github.com/ak47andrew/virtual-console/blob/main/src/flowchart-gen/src/main.rs"
click node_flow_graph "https://github.com/ak47andrew/virtual-console/blob/main/src/flowchart-gen/src/graph.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_source,node_manifest,node_palette toneBlue
class node_compiler_cli,node_compiler_entry,node_assembly_parser,node_operand_validation,node_asset_compiler toneAmber
class node_cartridge_model,node_manifest_model,node_vm_isa toneMint
class node_runtime_cli,node_emulator,node_vm_memory,node_debugger,node_launcher toneRose
class node_lsp,node_opcode_docs,node_flowchart,node_flow_graph,node_docs toneIndigo
```

## Components

### Cartridge Inputs

- [VEA assembly](https://github.com/ak47andrew/virtual-console/blob/main/examples/example_cartridge/source.vea): source input · `examples/example_cartridge/source.vea`
- [Cartridge manifest](https://github.com/ak47andrew/virtual-console/blob/main/examples/example_cartridge/manifest.toml): metadata input · `examples/example_cartridge/manifest.toml`
- [Palette asset](https://github.com/ak47andrew/virtual-console/blob/main/examples/example_cartridge/palette.pal): asset input · `examples/example_cartridge/palette.pal`

### Compiler

- [Compiler CLI](https://github.com/ak47andrew/virtual-console/blob/main/src/compiler/src/main.rs): Rust executable · `src/compiler/src/main.rs`
- [Compile orchestration](https://github.com/ak47andrew/virtual-console/blob/main/src/compiler/src/entry.rs): compiler dispatch · Coordinates compilation and diagnostics. · `src/compiler/src/entry.rs`
- [Assembly parser](https://github.com/ak47andrew/virtual-console/blob/main/src/compiler/src/vea/parsing.rs): parser · `src/compiler/src/vea/parsing.rs`
- [Operand validation](https://github.com/ak47andrew/virtual-console/blob/main/src/compiler/src/vea/operand_checking.rs): validator · `src/compiler/src/vea/operand_checking.rs`
- [Image & palette compilation](https://github.com/ak47andrew/virtual-console/blob/main/src/compiler/src/images/mod.rs): asset pipeline · `src/compiler/src/images/mod.rs`

### Shared Contract

- [Cartridge format](https://github.com/ak47andrew/virtual-console/blob/main/src/shared/src/cartridge.rs): shared contract · Defines cartridge representation and loading primitives. · `src/shared/src/cartridge.rs`
- [Manifest contract](https://github.com/ak47andrew/virtual-console/blob/main/src/shared/src/manifest.rs): shared contract · `src/shared/src/manifest.rs`
- [VM ISA contracts](https://github.com/ak47andrew/virtual-console/blob/main/src/shared/src/opcodes.rs): instruction model · Opcodes, operands, and registers shared by tools and runtime. · `src/shared/src/opcodes.rs`

### Execution

- [Runtime executable](https://github.com/ak47andrew/virtual-console/blob/main/src/runtime/src/main.rs): Rust executable · `src/runtime/src/main.rs`
- [VM emulator](https://github.com/ak47andrew/virtual-console/blob/main/src/runtime/src/emulator.rs): execution engine · Executes program instructions and control flow. · `src/runtime/src/emulator.rs`
- [VM memory](https://github.com/ak47andrew/virtual-console/blob/main/src/runtime/src/memory.rs): memory model · `src/runtime/src/memory.rs`
- [Debugger](https://github.com/ak47andrew/virtual-console/blob/main/src/runtime/src/debugger.rs): debug integration · `src/runtime/src/debugger.rs`
- [Launcher](https://github.com/ak47andrew/virtual-console/blob/main/src/launcher/src/main.rs): Rust executable · Supports UI and non-UI launch workflows. · `src/launcher/src/main.rs`

### Tooling & Docs

- [Language server](https://github.com/ak47andrew/virtual-console/blob/main/src/lsp/src/main.rs): Rust executable · `src/lsp/src/main.rs`
- **Opcode documentation package**: build input · Packaged into the language server at build time.
- [Flowchart generator](https://github.com/ak47andrew/virtual-console/blob/main/src/flowchart-gen/src/main.rs): Rust executable · Analyzes program control flow. · `src/flowchart-gen/src/main.rs`
- [Control-flow analysis](https://github.com/ak47andrew/virtual-console/blob/main/src/flowchart-gen/src/graph.rs): graph analysis · `src/flowchart-gen/src/graph.rs`
- **VM & assembler docs**: mdBook documentation

## Connections

- VEA assembly → Compiler CLI: compile
- Cartridge manifest → Compiler CLI: package metadata
- Palette asset → Compiler CLI: asset
- Compiler CLI → Compile orchestration: invokes
- Compile orchestration → Assembly parser: parses
- Assembly parser → Operand validation: validates operands
- Compile orchestration → Image & palette compilation: compiles assets
- Compile orchestration → Cartridge format: emits
- Compile orchestration → Manifest contract: uses
- Operand validation → VM ISA contracts: checks against
- Cartridge format → Runtime executable: compiled cartridge
- Runtime executable → VM emulator: runs
- VM emulator → VM memory: reads and writes
- VM emulator → Debugger: debug hooks
- VM emulator → VM ISA contracts: executes
- Launcher → Compiler CLI: launches workflow
- Launcher → Runtime executable: launches workflow
- Language server → Opcode documentation package: packages at build
- Language server → VM ISA contracts: aligns with
- Flowchart generator → Control-flow analysis: generates
- Control-flow analysis → VM ISA contracts: interprets control flow
- VM & assembler docs → VM ISA contracts: documents
- VM & assembler docs → Cartridge format: documents