# gearshift-interactive/cogwheel architecture

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

- Interactive diagram: https://gitdiagram.com/gearshift-interactive/cogwheel
- Repository: https://github.com/gearshift-interactive/cogwheel

## Overview

Cogwheel is a work-in-progress programming language implementation. Its principal workflow starts with a source-file argument, loads a module, finalizes it, compiles the resulting AST to bytecode, and runs that bytecode. The repository separates language front-end stages, semantic/type modeling, and runtime execution. The README documents language capabilities including functions, arrays, options, control flow, and stringification; these are represented by the compiler and VM rather than separate feature nodes. Sampled evidence shows main’s orchestration; internal module-loading and stage-to-stage calls are not fully visible, so those links are omitted.

Main entry points: [`src/main.c`](https://github.com/gearshift-interactive/cogwheel/blob/master/src/main.c) (Program entry), [`src/bank.c`](https://github.com/gearshift-interactive/cogwheel/blob/master/src/bank.c) (Allocation bank), [`src/semantic_analyzer.c`](https://github.com/gearshift-interactive/cogwheel/blob/master/src/semantic_analyzer.c) (Semantic analysis), [`src/vm.c`](https://github.com/gearshift-interactive/cogwheel/blob/master/src/vm.c) (Virtual machine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_front["Language front end"]
  node_modules["Module loading<br/>[module.c]"]
  node_lexer["Lexer<br/>[lexer.c]"]
  node_parser["Parser<br/>[parser.c]"]
  node_ast["AST model<br/>[node.c]"]
end

subgraph group_semantics["Language semantics"]
  node_analyzer["Semantic analysis"]
  node_types["Type system<br/>[type.c]"]
end

subgraph group_runtime["Execution runtime"]
  node_compiler["Bytecode compiler<br/>[compiler.c]"]
  node_vm["Virtual machine<br/>[vm.c]"]
  node_values["Runtime values<br/>[value.c]"]
  node_stack["Value stack<br/>[stack.c]"]
  node_globals["Global bindings<br/>[globals.h]"]
end

subgraph group_support["Runtime support"]
  node_bank["Allocation bank<br/>[bank.c]"]
  node_errors["Diagnostics<br/>[error.c]"]
end

node_user(("Source file user"))
node_main["Program entry<br/>[main.c]"]
node_stdio["Standard I/O"]

node_user -->|"provides source"| node_main
node_main -->|"loads and finalizes"| node_modules
node_main -->|"compiles AST"| node_compiler
node_main -->|"runs bytecode"| node_vm
node_main -->|"builds bindings"| node_globals
node_parser -->|"produces AST"| node_ast
node_analyzer -->|"analyzes AST"| node_ast
node_analyzer -->|"checks bindings"| node_globals
node_types -->|"uses tokens"| node_lexer
node_vm -->|"uses stack"| node_stack
node_vm -->|"executes values"| node_values
node_main -->|"prints results"| node_stdio
node_lexer -->|"reports errors"| node_errors
node_parser -->|"reports errors"| node_errors
node_analyzer -->|"reports errors"| node_errors
node_vm -->|"reports errors"| node_errors
node_modules -->|"allocates through"| node_bank
node_lexer -->|"allocates through"| node_bank
node_parser -->|"allocates through"| node_bank
node_analyzer -->|"allocates through"| node_bank
node_types -->|"allocates through"| node_bank

click node_main "https://github.com/gearshift-interactive/cogwheel/blob/master/src/main.c"
click node_modules "https://github.com/gearshift-interactive/cogwheel/blob/master/src/module.c"
click node_lexer "https://github.com/gearshift-interactive/cogwheel/blob/master/src/lexer.c"
click node_parser "https://github.com/gearshift-interactive/cogwheel/blob/master/src/parser.c"
click node_ast "https://github.com/gearshift-interactive/cogwheel/blob/master/src/node.c"
click node_analyzer "https://github.com/gearshift-interactive/cogwheel/blob/master/src/semantic_analyzer.c"
click node_types "https://github.com/gearshift-interactive/cogwheel/blob/master/src/type.c"
click node_compiler "https://github.com/gearshift-interactive/cogwheel/blob/master/src/compiler.c"
click node_vm "https://github.com/gearshift-interactive/cogwheel/blob/master/src/vm.c"
click node_values "https://github.com/gearshift-interactive/cogwheel/blob/master/src/value.c"
click node_stack "https://github.com/gearshift-interactive/cogwheel/blob/master/src/stack.c"
click node_globals "https://github.com/gearshift-interactive/cogwheel/blob/master/src/globals.h"
click node_bank "https://github.com/gearshift-interactive/cogwheel/blob/master/src/bank.c"
click node_errors "https://github.com/gearshift-interactive/cogwheel/blob/master/src/error.c"

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_modules,node_lexer,node_parser,node_ast,node_user toneBlue
class node_analyzer,node_types toneAmber
class node_compiler,node_vm,node_values,node_stack,node_globals toneMint
class node_bank,node_errors toneRose
class node_main toneTeal
class node_stdio toneIndigo
```

## Components

### Language front end

- [Module loading](https://github.com/gearshift-interactive/cogwheel/blob/master/src/module.c): `src/module.c`
- [Lexer](https://github.com/gearshift-interactive/cogwheel/blob/master/src/lexer.c): `src/lexer.c`
- [Parser](https://github.com/gearshift-interactive/cogwheel/blob/master/src/parser.c): `src/parser.c`
- [AST model](https://github.com/gearshift-interactive/cogwheel/blob/master/src/node.c): `src/node.c`

### Language semantics

- [Semantic analysis](https://github.com/gearshift-interactive/cogwheel/blob/master/src/semantic_analyzer.c): `src/semantic_analyzer.c`
- [Type system](https://github.com/gearshift-interactive/cogwheel/blob/master/src/type.c): `src/type.c`

### Execution runtime

- [Bytecode compiler](https://github.com/gearshift-interactive/cogwheel/blob/master/src/compiler.c): `src/compiler.c`
- [Virtual machine](https://github.com/gearshift-interactive/cogwheel/blob/master/src/vm.c): `src/vm.c`
- [Runtime values](https://github.com/gearshift-interactive/cogwheel/blob/master/src/value.c): `src/value.c`
- [Value stack](https://github.com/gearshift-interactive/cogwheel/blob/master/src/stack.c): `src/stack.c`
- [Global bindings](https://github.com/gearshift-interactive/cogwheel/blob/master/src/globals.h): `src/globals.h`

### Runtime support

- [Allocation bank](https://github.com/gearshift-interactive/cogwheel/blob/master/src/bank.c): `src/bank.c`
- [Diagnostics](https://github.com/gearshift-interactive/cogwheel/blob/master/src/error.c): `src/error.c`

### Other components

- **Source file user**
- [Program entry](https://github.com/gearshift-interactive/cogwheel/blob/master/src/main.c): `src/main.c`
- **Standard I/O**

## Connections

- Source file user → Program entry: provides source (evidence: `src/main.c`)
- Program entry → Module loading: loads and finalizes (evidence: `src/main.c`)
- Program entry → Bytecode compiler: compiles AST (evidence: `src/main.c`)
- Program entry → Virtual machine: runs bytecode (evidence: `src/main.c`)
- Program entry → Global bindings: builds bindings (evidence: `src/main.c`)
- Parser → AST model: produces AST
- Semantic analysis → AST model: analyzes AST
- Semantic analysis → Global bindings: checks bindings
- Type system → Lexer: uses tokens
- Virtual machine → Value stack: uses stack (evidence: `src/vm.c`)
- Virtual machine → Runtime values: executes values
- Program entry → Standard I/O: prints results (evidence: `src/main.c`)
- Lexer → Diagnostics: reports errors (evidence: `src/lexer.c`)
- Parser → Diagnostics: reports errors (evidence: `src/parser.c`)
- Semantic analysis → Diagnostics: reports errors (evidence: `src/semantic_analyzer.c`)
- Virtual machine → Diagnostics: reports errors (evidence: `src/vm.c`)
- Module loading → Allocation bank: allocates through (evidence: `src/module.c`)
- Lexer → Allocation bank: allocates through (evidence: `src/lexer.c`)
- Parser → Allocation bank: allocates through (evidence: `src/parser.c`)
- Semantic analysis → Allocation bank: allocates through (evidence: `src/semantic_analyzer.c`)
- Type system → Allocation bank: allocates through (evidence: `src/type.c`)
