# zoolah/cove architecture

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

- Interactive diagram: https://gitdiagram.com/zoolah/cove
- Repository: https://github.com/zoolah/cove

## Overview

Cove is a lightweight stack-based language: users provide source through the CLI or browser playground, the compiler turns it into bytecode, and the virtual machine executes it. The compiler covers expression parsing and statement compilation; VM instruction handlers implement arithmetic, control flow, I/O, variables, tables, and classes. Standalone executable generation is another documented CLI capability. The README documents the pipeline and language features; some implementation relationships below are based on excerpts, while unsampled details are left unconnected.

Main entry points: [`src/vm/machine.hpp`](https://github.com/zoolah/cove/blob/main/src/vm/machine.hpp) (VM run loop), [`src/compiler/compiler.hpp`](https://github.com/zoolah/cove/blob/main/src/compiler/compiler.hpp) (Compile blocks), [`src/entry.cpp`](https://github.com/zoolah/cove/blob/main/src/entry.cpp) (CLI entry), [`src/compiler/components/tokenizer.cpp`](https://github.com/zoolah/cove/blob/main/src/compiler/components/tokenizer.cpp) (Tokenizer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_compiler["Compiler"]
  node_tokenizer["Tokenizer<br/>[tokenizer.cpp]"]
  node_compiler_core["Compile blocks<br/>[compiler.hpp]"]
  node_statements["Statement compilers"]
  node_definitions["Definitions<br/>[definitions.cpp]"]
  node_evaluator["Expression evaluator<br/>[evaluator.cpp]"]
  node_bytecode_printer["Bytecode printer<br/>[printer.cpp]"]
end

subgraph group_runtime["Virtual machine"]
  node_machine["VM run loop<br/>[machine.hpp]"]
  node_stack_ops["Stack operations<br/>[stack.cpp]"]
  node_arithmetic_ops["Arithmetic<br/>[arithmetic.cpp]"]
  node_io_ops["Input and output<br/>[io.cpp]"]
  node_variable_ops["Variable scopes<br/>[vars.cpp]"]
  node_control_ops["Control flow<br/>[cflow.cpp]"]
  node_table_ops["Tables<br/>[tables.cpp]"]
  node_class_ops["Classes<br/>[classes.cpp]"]
end

subgraph group_delivery["User interfaces"]
  node_cli["CLI entry<br/>[entry.cpp]"]
  node_playground["Web playground<br/>[app.js]"]
  node_standalone["Standalone packaging<br/>[standalone.cpp]"]
  node_wasm["WebAssembly runtime<br/>[cove.wasm]"]
end

node_cli_user(("CLI user"))
node_playground_user(("Playground user"))
node_shared_types["Tokens and bytecode<br/>[structs.hpp]"]

node_cli_user -->|"runs source"| node_cli
node_playground_user -->|"uses playground"| node_playground
node_cli -->|"tokenizes source"| node_tokenizer
node_tokenizer -->|"supplies tokens"| node_compiler_core
node_compiler_core -->|"dispatches statements"| node_statements
node_compiler_core -->|"evaluates expressions"| node_evaluator
node_statements -->|"compiles definitions"| node_definitions
node_definitions -->|"compiles expressions"| node_evaluator
node_compiler_core -->|"prints bytecode"| node_bytecode_printer
node_compiler_core -->|"emits instructions"| node_shared_types
node_cli -->|"compiles source"| node_compiler_core
node_cli -->|"runs bytecode"| node_machine
node_machine -->|"dispatches opcodes"| node_stack_ops
node_machine -->|"dispatches opcodes"| node_arithmetic_ops
node_machine -->|"dispatches opcodes"| node_io_ops
node_machine -->|"dispatches opcodes"| node_variable_ops
node_machine -->|"dispatches opcodes"| node_control_ops
node_machine -->|"dispatches opcodes"| node_table_ops
node_machine -->|"dispatches opcodes"| node_class_ops
node_machine -->|"executes instructions"| node_shared_types
node_cli -.->|"supports standalone mode"| node_standalone
node_playground -.->|"uses runtime"| node_wasm

click node_cli "https://github.com/zoolah/cove/blob/main/src/entry.cpp"
click node_playground "https://github.com/zoolah/cove/blob/main/web/app.js"
click node_tokenizer "https://github.com/zoolah/cove/blob/main/src/compiler/components/tokenizer.cpp"
click node_compiler_core "https://github.com/zoolah/cove/blob/main/src/compiler/compiler.hpp"
click node_statements "https://github.com/zoolah/cove/tree/main/src/compiler/statements"
click node_definitions "https://github.com/zoolah/cove/blob/main/src/compiler/statements/definitions.cpp"
click node_evaluator "https://github.com/zoolah/cove/blob/main/src/compiler/components/evaluator.cpp"
click node_bytecode_printer "https://github.com/zoolah/cove/blob/main/src/compiler/components/printer.cpp"
click node_shared_types "https://github.com/zoolah/cove/blob/main/src/shared/structs.hpp"
click node_machine "https://github.com/zoolah/cove/blob/main/src/vm/machine.hpp"
click node_stack_ops "https://github.com/zoolah/cove/blob/main/src/vm/ops/stack.cpp"
click node_arithmetic_ops "https://github.com/zoolah/cove/blob/main/src/vm/ops/arithmetic.cpp"
click node_io_ops "https://github.com/zoolah/cove/blob/main/src/vm/ops/io.cpp"
click node_variable_ops "https://github.com/zoolah/cove/blob/main/src/vm/ops/vars.cpp"
click node_control_ops "https://github.com/zoolah/cove/blob/main/src/vm/ops/cflow.cpp"
click node_table_ops "https://github.com/zoolah/cove/blob/main/src/vm/ops/tables.cpp"
click node_class_ops "https://github.com/zoolah/cove/blob/main/src/vm/ops/classes.cpp"
click node_standalone "https://github.com/zoolah/cove/blob/main/src/standalone/standalone.cpp"
click node_wasm "https://github.com/zoolah/cove/blob/main/web/cove.wasm"

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_tokenizer,node_compiler_core,node_statements,node_definitions,node_evaluator,node_bytecode_printer,node_cli_user,node_playground_user toneBlue
class node_machine,node_stack_ops,node_arithmetic_ops,node_io_ops,node_variable_ops,node_control_ops,node_table_ops,node_class_ops toneAmber
class node_cli,node_playground,node_standalone,node_wasm toneMint
class node_shared_types toneTeal
```

## Components

### Compiler

- [Tokenizer](https://github.com/zoolah/cove/blob/main/src/compiler/components/tokenizer.cpp): `src/compiler/components/tokenizer.cpp`
- [Compile blocks](https://github.com/zoolah/cove/blob/main/src/compiler/compiler.hpp): `src/compiler/compiler.hpp`
- [Statement compilers](https://github.com/zoolah/cove/tree/main/src/compiler/statements): `src/compiler/statements`
- [Definitions](https://github.com/zoolah/cove/blob/main/src/compiler/statements/definitions.cpp): `src/compiler/statements/definitions.cpp`
- [Expression evaluator](https://github.com/zoolah/cove/blob/main/src/compiler/components/evaluator.cpp): `src/compiler/components/evaluator.cpp`
- [Bytecode printer](https://github.com/zoolah/cove/blob/main/src/compiler/components/printer.cpp): `src/compiler/components/printer.cpp`

### Virtual machine

- [VM run loop](https://github.com/zoolah/cove/blob/main/src/vm/machine.hpp): `src/vm/machine.hpp`
- [Stack operations](https://github.com/zoolah/cove/blob/main/src/vm/ops/stack.cpp): `src/vm/ops/stack.cpp`
- [Arithmetic](https://github.com/zoolah/cove/blob/main/src/vm/ops/arithmetic.cpp): `src/vm/ops/arithmetic.cpp`
- [Input and output](https://github.com/zoolah/cove/blob/main/src/vm/ops/io.cpp): `src/vm/ops/io.cpp`
- [Variable scopes](https://github.com/zoolah/cove/blob/main/src/vm/ops/vars.cpp): `src/vm/ops/vars.cpp`
- [Control flow](https://github.com/zoolah/cove/blob/main/src/vm/ops/cflow.cpp): `src/vm/ops/cflow.cpp`
- [Tables](https://github.com/zoolah/cove/blob/main/src/vm/ops/tables.cpp): `src/vm/ops/tables.cpp`
- [Classes](https://github.com/zoolah/cove/blob/main/src/vm/ops/classes.cpp): `src/vm/ops/classes.cpp`

### User interfaces

- [CLI entry](https://github.com/zoolah/cove/blob/main/src/entry.cpp): `src/entry.cpp`
- [Web playground](https://github.com/zoolah/cove/blob/main/web/app.js): `web/app.js`
- [Standalone packaging](https://github.com/zoolah/cove/blob/main/src/standalone/standalone.cpp): `src/standalone/standalone.cpp`
- [WebAssembly runtime](https://github.com/zoolah/cove/blob/main/web/cove.wasm): `web/cove.wasm`

### Other components

- **CLI user**
- **Playground user**
- [Tokens and bytecode](https://github.com/zoolah/cove/blob/main/src/shared/structs.hpp): `src/shared/structs.hpp`

## Connections

- CLI user → CLI entry: runs source (evidence: `README.md`)
- Playground user → Web playground: uses playground (evidence: `README.md`)
- CLI entry → Tokenizer: tokenizes source (evidence: `README.md`)
- Tokenizer → Compile blocks: supplies tokens (evidence: `README.md`)
- Compile blocks → Statement compilers: dispatches statements (evidence: `README.md`)
- Compile blocks → Expression evaluator: evaluates expressions (evidence: `src/compiler/compiler.hpp`)
- Statement compilers → Definitions: compiles definitions (evidence: `README.md`)
- Definitions → Expression evaluator: compiles expressions (evidence: `src/compiler/statements/definitions.cpp`)
- Compile blocks → Bytecode printer: prints bytecode (evidence: `src/compiler/components/printer.cpp`)
- Compile blocks → Tokens and bytecode: emits instructions (evidence: `src/compiler/compiler.hpp`)
- CLI entry → Compile blocks: compiles source (evidence: `src/entry.cpp`)
- CLI entry → VM run loop: runs bytecode (evidence: `src/entry.cpp`)
- VM run loop → Stack operations: dispatches opcodes (evidence: `src/vm/machine.hpp`)
- VM run loop → Arithmetic: dispatches opcodes (evidence: `src/vm/machine.hpp`)
- VM run loop → Input and output: dispatches opcodes (evidence: `src/vm/machine.hpp`)
- VM run loop → Variable scopes: dispatches opcodes (evidence: `src/vm/machine.hpp`)
- VM run loop → Control flow: dispatches opcodes (evidence: `src/vm/machine.hpp`)
- VM run loop → Tables: dispatches opcodes (evidence: `src/vm/machine.hpp`)
- VM run loop → Classes: dispatches opcodes (evidence: `src/vm/machine.hpp`)
- VM run loop → Tokens and bytecode: executes instructions (evidence: `src/vm/machine.hpp`)
- CLI entry → Standalone packaging: supports standalone mode (evidence: `README.md`)
- Web playground → WebAssembly runtime: uses runtime
