# omnidirectional-foundation/burryn architecture

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

- Interactive diagram: https://gitdiagram.com/omnidirectional-foundation/burryn
- Repository: https://github.com/omnidirectional-foundation/burryn

## Overview

Burryn is a self-hosted programming language and toolchain. The primary workflow takes source through lexing, parsing, module loading and type checking, then either compiles to bytecode for the VM or emits native code through the C or x86 backend. The CLI also exposes formatting, disassembly, testing and language-server support. The README documents the major stages and backends; sampled source confirms parts of the C runtime and VS Code client, but not the internal call wiring of most Burryn modules, so uncertain links are omitted.

Main entry points: [`compiler/cli`](https://github.com/omnidirectional-foundation/burryn/tree/main/compiler/cli) (CLI Commands), [`compiler/main.bur`](https://github.com/omnidirectional-foundation/burryn/blob/main/compiler/main.bur) (bur CLI), [`compiler/backends/c/cgen.bur`](https://github.com/omnidirectional-foundation/burryn/blob/main/compiler/backends/c/cgen.bur) (C Backend), [`compiler/bytecode/compiler.bur`](https://github.com/omnidirectional-foundation/burryn/blob/main/compiler/bytecode/compiler.bur) (Bytecode Compiler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_front["Language Frontend"]
  node_lexer["Lexer<br/>[lexer.bur]"]
  node_parser["Parser<br/>[parser.bur]"]
  node_ast["AST<br/>[ast.bur]"]
  node_typecheck["Type Checker<br/>[ty_check.bur]"]
  node_modules["Module Loader<br/>[module.bur]"]
end

subgraph group_execution["Execution"]
  node_bytecode["Bytecode Compiler<br/>[compiler.bur]"]
  node_vm["Bytecode VM<br/>[vm.bur]"]
end

subgraph group_native["Native Backends"]
  node_cbackend["C Backend<br/>[cgen.bur]"]
  node_cruntime["C Runtime<br/>[burrt_impl.c]"]
  node_x86backend["x86-64 Backend"]
  node_llvmbackend["LLVM Backend<br/>[llgen.bur]"]
  node_native_runtime["Native Runtime Services<br/>[burrt_natives.c]"]
end

subgraph group_tools["Developer Tools"]
  node_cli["bur CLI<br/>[main.bur]"]
  node_cli_commands["CLI Commands"]
  node_formatter["Formatter<br/>[format.bur]"]
  node_disassembler["Bytecode Disassembler<br/>[dump.bur]"]
  node_lsp["Language Server<br/>[lsp.bur]"]
  node_vscode["VS Code Client<br/>[extension.ts]"]
end

subgraph group_libraries["Language Libraries"]
  node_stdlib["Standard Library"]
end

node_user(("Language User"))
node_source["Burryn Source"]
node_binary["Native Program"]
node_program_output["Program Result"]

node_user -->|"invokes"| node_cli
node_source -->|"provides input"| node_cli
node_cli -->|"dispatches"| node_cli_commands
node_cli_commands -->|"starts compilation"| node_lexer
node_lexer -->|"tokens"| node_parser
node_parser -->|"builds"| node_ast
node_cli_commands -->|"loads packages"| node_modules
node_cli_commands -->|"checks source"| node_typecheck
node_typecheck -->|"typed program"| node_bytecode
node_cli_commands -->|"compiles"| node_bytecode
node_cli_commands -->|"runs on VM"| node_vm
node_bytecode -->|"executes bytecode"| node_vm
node_cli_commands -->|"builds with C"| node_cbackend
node_cbackend -->|"uses runtime"| node_cruntime
node_cruntime -->|"calls natives"| node_native_runtime
node_cli_commands -->|"builds with x86"| node_x86backend
node_cli_commands -.->|"selects backend"| node_llvmbackend
node_cbackend -->|"emits program"| node_binary
node_x86backend -->|"emits program"| node_binary
node_cli_commands -->|"formats source"| node_formatter
node_cli_commands -->|"disassembles code"| node_disassembler
node_user -->|"edits source"| node_vscode
node_vscode -->|"starts bur lsp"| node_cli
node_cli -->|"serves requests"| node_lsp
node_cli_commands -->|"exposes modules"| node_stdlib
node_binary -->|"produces"| node_program_output
node_vm -->|"produces"| node_program_output

click node_cli "https://github.com/omnidirectional-foundation/burryn/blob/main/compiler/main.bur"
click node_cli_commands "https://github.com/omnidirectional-foundation/burryn/tree/main/compiler/cli"
click node_lexer "https://github.com/omnidirectional-foundation/burryn/blob/main/compiler/frontend/lexer.bur"
click node_parser "https://github.com/omnidirectional-foundation/burryn/blob/main/compiler/frontend/parser.bur"
click node_ast "https://github.com/omnidirectional-foundation/burryn/blob/main/compiler/frontend/ast.bur"
click node_typecheck "https://github.com/omnidirectional-foundation/burryn/blob/main/compiler/frontend/ty_check.bur"
click node_modules "https://github.com/omnidirectional-foundation/burryn/blob/main/compiler/module/module.bur"
click node_bytecode "https://github.com/omnidirectional-foundation/burryn/blob/main/compiler/bytecode/compiler.bur"
click node_vm "https://github.com/omnidirectional-foundation/burryn/blob/main/compiler/bytecode/vm.bur"
click node_cbackend "https://github.com/omnidirectional-foundation/burryn/blob/main/compiler/backends/c/cgen.bur"
click node_cruntime "https://github.com/omnidirectional-foundation/burryn/blob/main/runtime/burrt_impl.c"
click node_x86backend "https://github.com/omnidirectional-foundation/burryn/tree/main/compiler/backends/x86"
click node_llvmbackend "https://github.com/omnidirectional-foundation/burryn/blob/main/compiler/backends/llvm/llgen.bur"
click node_formatter "https://github.com/omnidirectional-foundation/burryn/blob/main/compiler/tooling/format.bur"
click node_disassembler "https://github.com/omnidirectional-foundation/burryn/blob/main/compiler/tooling/dump.bur"
click node_lsp "https://github.com/omnidirectional-foundation/burryn/blob/main/compiler/tooling/lsp.bur"
click node_vscode "https://github.com/omnidirectional-foundation/burryn/blob/main/editors/vscode/src/extension.ts"
click node_stdlib "https://github.com/omnidirectional-foundation/burryn/tree/main/std"
click node_native_runtime "https://github.com/omnidirectional-foundation/burryn/blob/main/runtime/burrt_natives.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_lexer,node_parser,node_ast,node_typecheck,node_modules,node_user toneBlue
class node_bytecode,node_vm toneAmber
class node_cbackend,node_cruntime,node_x86backend,node_llvmbackend,node_native_runtime toneMint
class node_cli,node_cli_commands,node_formatter,node_disassembler,node_lsp,node_vscode toneRose
class node_stdlib,node_source,node_binary,node_program_output toneIndigo
```

## Components

### Language Frontend

- [Lexer](https://github.com/omnidirectional-foundation/burryn/blob/main/compiler/frontend/lexer.bur): `compiler/frontend/lexer.bur`
- [Parser](https://github.com/omnidirectional-foundation/burryn/blob/main/compiler/frontend/parser.bur): `compiler/frontend/parser.bur`
- [AST](https://github.com/omnidirectional-foundation/burryn/blob/main/compiler/frontend/ast.bur): `compiler/frontend/ast.bur`
- [Type Checker](https://github.com/omnidirectional-foundation/burryn/blob/main/compiler/frontend/ty_check.bur): `compiler/frontend/ty_check.bur`
- [Module Loader](https://github.com/omnidirectional-foundation/burryn/blob/main/compiler/module/module.bur): `compiler/module/module.bur`

### Execution

- [Bytecode Compiler](https://github.com/omnidirectional-foundation/burryn/blob/main/compiler/bytecode/compiler.bur): `compiler/bytecode/compiler.bur`
- [Bytecode VM](https://github.com/omnidirectional-foundation/burryn/blob/main/compiler/bytecode/vm.bur): `compiler/bytecode/vm.bur`

### Native Backends

- [C Backend](https://github.com/omnidirectional-foundation/burryn/blob/main/compiler/backends/c/cgen.bur): `compiler/backends/c/cgen.bur`
- [C Runtime](https://github.com/omnidirectional-foundation/burryn/blob/main/runtime/burrt_impl.c): `runtime/burrt_impl.c`
- [x86-64 Backend](https://github.com/omnidirectional-foundation/burryn/tree/main/compiler/backends/x86): `compiler/backends/x86`
- [LLVM Backend](https://github.com/omnidirectional-foundation/burryn/blob/main/compiler/backends/llvm/llgen.bur): `compiler/backends/llvm/llgen.bur`
- [Native Runtime Services](https://github.com/omnidirectional-foundation/burryn/blob/main/runtime/burrt_natives.c): `runtime/burrt_natives.c`

### Developer Tools

- [bur CLI](https://github.com/omnidirectional-foundation/burryn/blob/main/compiler/main.bur): `compiler/main.bur`
- [CLI Commands](https://github.com/omnidirectional-foundation/burryn/tree/main/compiler/cli): `compiler/cli`
- [Formatter](https://github.com/omnidirectional-foundation/burryn/blob/main/compiler/tooling/format.bur): `compiler/tooling/format.bur`
- [Bytecode Disassembler](https://github.com/omnidirectional-foundation/burryn/blob/main/compiler/tooling/dump.bur): `compiler/tooling/dump.bur`
- [Language Server](https://github.com/omnidirectional-foundation/burryn/blob/main/compiler/tooling/lsp.bur): `compiler/tooling/lsp.bur`
- [VS Code Client](https://github.com/omnidirectional-foundation/burryn/blob/main/editors/vscode/src/extension.ts): `editors/vscode/src/extension.ts`

### Language Libraries

- [Standard Library](https://github.com/omnidirectional-foundation/burryn/tree/main/std): `std`

### Other components

- **Language User**
- **Burryn Source**
- **Native Program**
- **Program Result**

## Connections

- Language User → bur CLI: invokes
- Burryn Source → bur CLI: provides input
- bur CLI → CLI Commands: dispatches
- CLI Commands → Lexer: starts compilation
- Lexer → Parser: tokens
- Parser → AST: builds
- CLI Commands → Module Loader: loads packages
- CLI Commands → Type Checker: checks source
- Type Checker → Bytecode Compiler: typed program
- CLI Commands → Bytecode Compiler: compiles
- CLI Commands → Bytecode VM: runs on VM
- Bytecode Compiler → Bytecode VM: executes bytecode
- CLI Commands → C Backend: builds with C
- C Backend → C Runtime: uses runtime
- C Runtime → Native Runtime Services: calls natives
- CLI Commands → x86-64 Backend: builds with x86
- CLI Commands → LLVM Backend: selects backend
- C Backend → Native Program: emits program
- x86-64 Backend → Native Program: emits program
- CLI Commands → Formatter: formats source
- CLI Commands → Bytecode Disassembler: disassembles code
- Language User → VS Code Client: edits source
- VS Code Client → bur CLI: starts bur lsp
- bur CLI → Language Server: serves requests
- CLI Commands → Standard Library: exposes modules
- Native Program → Program Result: produces
- Bytecode VM → Program Result: produces