# aardappel/goose architecture

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

- Interactive diagram: https://gitdiagram.com/aardappel/goose
- Repository: https://github.com/aardappel/goose

## Overview

Goose is a memory-safe systems programming language and compiler. Its main workflow takes source files through parsing, semantic checks and optimization, then generates C or runs programs through its bundled runtime/JIT. The repository also provides a language server, a VS Code extension and a Tree-sitter grammar. The graph reflects documented capabilities and the sampled driver/editor wiring; several compiler-phase links rely on the driver’s indexed references, while unsampled subsystem internals are left unconnected where their callers are not shown.

Main entry points: [`src/main.cpp`](https://github.com/aardappel/goose/blob/master/src/main.cpp) (Compiler driver), [`src/typecheck.h`](https://github.com/aardappel/goose/blob/master/src/typecheck.h) (Type checker), [`src/codegen.h`](https://github.com/aardappel/goose/blob/master/src/codegen.h) (Code generator), [`vscode/src/extension.js`](https://github.com/aardappel/goose/blob/master/vscode/src/extension.js) (VS Code extension)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_compiler["Compiler workflow"]
  node_driver["Compiler driver<br/>[main.cpp]"]
  node_lexer["Lexer<br/>[lexer.h]"]
  node_parser["Parser<br/>[parser.h]"]
  node_ast["AST model<br/>[ast.h]"]
end

subgraph group_analysis["Static analysis"]
  node_typecheck["Type checker<br/>[typecheck.h]"]
  node_builtincheck["Builtin checks"]
  node_callcheck["Call checks<br/>[typecheck_calls.h]"]
  node_exprcheck["Expression checks<br/>[typecheck_exprs.h]"]
  node_flowcheck["Flow checks<br/>[typecheck_flow.h]"]
  node_typechecks["Type rules<br/>[typecheck_types.h]"]
  node_bounds["Bounds analysis<br/>[bce.h]"]
  node_optimizer["Optimizer<br/>[optimize.h]"]
end

subgraph group_execution["Code generation and runtime"]
  node_codegen["Code generator<br/>[codegen.h]"]
  node_codegen_builtins["Builtin emission<br/>[codegen_builtins.h]"]
  node_codegen_types["Type emission<br/>[codegen_types.h]"]
  node_codegen_values["Value emission<br/>[codegen_values.h]"]
  node_runtime["Inline runtime<br/>[runtime_inline.h]"]
  node_runtime_impl["Runtime implementation<br/>[runtime_impl.h]"]
end

subgraph group_editor["Editor tooling"]
  node_lsp["Language server<br/>[lsp.h]"]
  node_vscode["VS Code extension<br/>[extension.js]"]
  node_vscode_config["Editor configuration<br/>[config.js]"]
  node_vscode_client["Server client<br/>[client.js]"]
  node_diagnostics["Diagnostics<br/>[diagnostics.js]"]
end

subgraph group_syntax["Syntax tooling"]
  node_treegrammar["Tree-sitter grammar<br/>[grammar.js]"]
  node_scanner["Comment scanner<br/>[scanner.c]"]
end

node_user(("Goose developer"))

node_user -->|"invokes"| node_driver
node_driver -->|"uses"| node_lexer
node_driver -->|"uses"| node_parser
node_parser -->|"builds"| node_ast
node_driver -.->|"runs checks"| node_typecheck
node_driver -->|"runs analysis"| node_bounds
node_driver -.->|"optimizes"| node_optimizer
node_typecheck -->|"delegates to"| node_builtincheck
node_typecheck -->|"delegates to"| node_callcheck
node_typecheck -->|"delegates to"| node_exprcheck
node_typecheck -->|"delegates to"| node_flowcheck
node_typecheck -.->|"delegates to"| node_typechecks
node_driver -.->|"generates code"| node_codegen
node_codegen -.->|"delegates to"| node_codegen_builtins
node_codegen -.->|"delegates to"| node_codegen_types
node_codegen -.->|"delegates to"| node_codegen_values
node_driver -.->|"embeds runtime"| node_runtime
node_runtime -.->|"includes implementation"| node_runtime_impl
node_user -->|"uses editor"| node_vscode
node_vscode -->|"loads settings"| node_vscode_config
node_vscode -->|"parses results"| node_diagnostics
node_vscode -->|"starts client"| node_vscode_client
node_vscode_client -->|"starts server"| node_lsp
node_user -.->|"edits source"| node_treegrammar
node_treegrammar -->|"uses scanner"| node_scanner

click node_driver "https://github.com/aardappel/goose/blob/master/src/main.cpp"
click node_lexer "https://github.com/aardappel/goose/blob/master/src/lexer.h"
click node_parser "https://github.com/aardappel/goose/blob/master/src/parser.h"
click node_ast "https://github.com/aardappel/goose/blob/master/src/ast.h"
click node_typecheck "https://github.com/aardappel/goose/blob/master/src/typecheck.h"
click node_builtincheck "https://github.com/aardappel/goose/blob/master/src/typecheck_builtins.h"
click node_callcheck "https://github.com/aardappel/goose/blob/master/src/typecheck_calls.h"
click node_exprcheck "https://github.com/aardappel/goose/blob/master/src/typecheck_exprs.h"
click node_flowcheck "https://github.com/aardappel/goose/blob/master/src/typecheck_flow.h"
click node_typechecks "https://github.com/aardappel/goose/blob/master/src/typecheck_types.h"
click node_bounds "https://github.com/aardappel/goose/blob/master/src/bce.h"
click node_optimizer "https://github.com/aardappel/goose/blob/master/src/optimize.h"
click node_codegen "https://github.com/aardappel/goose/blob/master/src/codegen.h"
click node_codegen_builtins "https://github.com/aardappel/goose/blob/master/src/codegen_builtins.h"
click node_codegen_types "https://github.com/aardappel/goose/blob/master/src/codegen_types.h"
click node_codegen_values "https://github.com/aardappel/goose/blob/master/src/codegen_values.h"
click node_runtime "https://github.com/aardappel/goose/blob/master/src/runtime_inline.h"
click node_runtime_impl "https://github.com/aardappel/goose/blob/master/src/runtime/runtime_impl.h"
click node_lsp "https://github.com/aardappel/goose/blob/master/src/lsp.h"
click node_vscode "https://github.com/aardappel/goose/blob/master/vscode/src/extension.js"
click node_vscode_config "https://github.com/aardappel/goose/blob/master/vscode/src/config.js"
click node_vscode_client "https://github.com/aardappel/goose/blob/master/vscode/src/client.js"
click node_diagnostics "https://github.com/aardappel/goose/blob/master/vscode/src/diagnostics.js"
click node_treegrammar "https://github.com/aardappel/goose/blob/master/tree-sitter/grammar.js"
click node_scanner "https://github.com/aardappel/goose/blob/master/tree-sitter/src/scanner.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_driver,node_lexer,node_parser,node_ast toneBlue
class node_typecheck,node_builtincheck,node_callcheck,node_exprcheck,node_flowcheck,node_typechecks,node_bounds,node_optimizer toneAmber
class node_codegen,node_codegen_builtins,node_codegen_types,node_codegen_values,node_runtime,node_runtime_impl toneMint
class node_lsp,node_vscode,node_vscode_config,node_vscode_client,node_diagnostics toneRose
class node_treegrammar,node_scanner,node_user toneIndigo
```

## Components

### Compiler workflow

- [Compiler driver](https://github.com/aardappel/goose/blob/master/src/main.cpp): `src/main.cpp`
- [Lexer](https://github.com/aardappel/goose/blob/master/src/lexer.h): `src/lexer.h`
- [Parser](https://github.com/aardappel/goose/blob/master/src/parser.h): `src/parser.h`
- [AST model](https://github.com/aardappel/goose/blob/master/src/ast.h): `src/ast.h`

### Static analysis

- [Type checker](https://github.com/aardappel/goose/blob/master/src/typecheck.h): `src/typecheck.h`
- [Builtin checks](https://github.com/aardappel/goose/blob/master/src/typecheck_builtins.h): `src/typecheck_builtins.h`
- [Call checks](https://github.com/aardappel/goose/blob/master/src/typecheck_calls.h): `src/typecheck_calls.h`
- [Expression checks](https://github.com/aardappel/goose/blob/master/src/typecheck_exprs.h): `src/typecheck_exprs.h`
- [Flow checks](https://github.com/aardappel/goose/blob/master/src/typecheck_flow.h): `src/typecheck_flow.h`
- [Type rules](https://github.com/aardappel/goose/blob/master/src/typecheck_types.h): `src/typecheck_types.h`
- [Bounds analysis](https://github.com/aardappel/goose/blob/master/src/bce.h): `src/bce.h`
- [Optimizer](https://github.com/aardappel/goose/blob/master/src/optimize.h): `src/optimize.h`

### Code generation and runtime

- [Code generator](https://github.com/aardappel/goose/blob/master/src/codegen.h): `src/codegen.h`
- [Builtin emission](https://github.com/aardappel/goose/blob/master/src/codegen_builtins.h): `src/codegen_builtins.h`
- [Type emission](https://github.com/aardappel/goose/blob/master/src/codegen_types.h): `src/codegen_types.h`
- [Value emission](https://github.com/aardappel/goose/blob/master/src/codegen_values.h): `src/codegen_values.h`
- [Inline runtime](https://github.com/aardappel/goose/blob/master/src/runtime_inline.h): `src/runtime_inline.h`
- [Runtime implementation](https://github.com/aardappel/goose/blob/master/src/runtime/runtime_impl.h): `src/runtime/runtime_impl.h`

### Editor tooling

- [Language server](https://github.com/aardappel/goose/blob/master/src/lsp.h): `src/lsp.h`
- [VS Code extension](https://github.com/aardappel/goose/blob/master/vscode/src/extension.js): `vscode/src/extension.js`
- [Editor configuration](https://github.com/aardappel/goose/blob/master/vscode/src/config.js): `vscode/src/config.js`
- [Server client](https://github.com/aardappel/goose/blob/master/vscode/src/client.js): `vscode/src/client.js`
- [Diagnostics](https://github.com/aardappel/goose/blob/master/vscode/src/diagnostics.js): `vscode/src/diagnostics.js`

### Syntax tooling

- [Tree-sitter grammar](https://github.com/aardappel/goose/blob/master/tree-sitter/grammar.js): `tree-sitter/grammar.js`
- [Comment scanner](https://github.com/aardappel/goose/blob/master/tree-sitter/src/scanner.c): `tree-sitter/src/scanner.c`

### Other components

- **Goose developer**

## Connections

- Goose developer → Compiler driver: invokes (evidence: `src/main.cpp`)
- Compiler driver → Lexer: uses (evidence: `src/main.cpp`)
- Compiler driver → Parser: uses (evidence: `src/main.cpp`)
- Parser → AST model: builds (evidence: `src/parser.h`)
- Compiler driver → Type checker: runs checks (evidence: `src/main.cpp`)
- Compiler driver → Bounds analysis: runs analysis (evidence: `src/main.cpp`)
- Compiler driver → Optimizer: optimizes (evidence: `src/main.cpp`)
- Type checker → Builtin checks: delegates to (evidence: `src/typecheck_builtins.h`)
- Type checker → Call checks: delegates to (evidence: `src/typecheck_calls.h`)
- Type checker → Expression checks: delegates to (evidence: `src/typecheck_exprs.h`)
- Type checker → Flow checks: delegates to (evidence: `src/typecheck_flow.h`)
- Type checker → Type rules: delegates to
- Compiler driver → Code generator: generates code (evidence: `src/main.cpp`)
- Code generator → Builtin emission: delegates to
- Code generator → Type emission: delegates to
- Code generator → Value emission: delegates to
- Compiler driver → Inline runtime: embeds runtime (evidence: `src/main.cpp`)
- Inline runtime → Runtime implementation: includes implementation
- Goose developer → VS Code extension: uses editor (evidence: `vscode/src/extension.js`)
- VS Code extension → Editor configuration: loads settings (evidence: `vscode/src/extension.js`)
- VS Code extension → Diagnostics: parses results (evidence: `vscode/src/extension.js`)
- VS Code extension → Server client: starts client (evidence: `vscode/src/extension.js`)
- Server client → Language server: starts server (evidence: `vscode/src/client.js`)
- Goose developer → Tree-sitter grammar: edits source
- Tree-sitter grammar → Comment scanner: uses scanner (evidence: `tree-sitter/src/scanner.c`)