# jebailey/foster architecture

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

- Interactive diagram: https://gitdiagram.com/jebailey/foster
- Repository: https://github.com/jebailey/foster

## Overview

Foster is an experimental statically typed language and Rust-based toolchain. Its main workflow takes a project or source file through package discovery and checked compilation, then runs it on the register VM or builds a native executable; other user-facing branches include formatting, packing, testing, documentation, and editor support. The graph follows the documented workflow and sampled compiler/codegen structure. Some capabilities are documented but their implementations were not sampled, so those nodes have limited path detail and only documented relationships.

Main entry points: [`compiler/src/compiler/pipeline.rs`](https://github.com/jebailey/foster/blob/main/compiler/src/compiler/pipeline.rs) (Checked compilation), [`compiler/src/codegen/shared.rs`](https://github.com/jebailey/foster/blob/main/compiler/src/codegen/shared.rs) (Shared SSA and sealing), [`compiler/src/native/program.rs`](https://github.com/jebailey/foster/blob/main/compiler/src/native/program.rs) (Native backend), [`src/main.rs`](https://github.com/jebailey/foster/blob/main/src/main.rs) (Foster CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_toolchain["Toolchain entry"]
  node_cli["Foster CLI<br/>[main.rs]"]
  node_project["Project handling<br/>[project.rs]"]
  node_package["Package modules<br/>[package.rs]"]
end

subgraph group_compiler["Language compiler"]
  node_lexer["Lexer<br/>[lexer.rs]"]
  node_parser["Parser and AST"]
  node_hir["HIR lowering<br/>[hir.rs]"]
  node_typecheck["Type and effect checks"]
  node_ownership["Ownership checks"]
  node_pipeline["Checked compilation<br/>[pipeline.rs]"]
  node_construction["IR construction<br/>[construction.rs]"]
  node_shared_ir["Shared SSA and sealing<br/>[shared.rs]"]
end

subgraph group_execution["Execution backends"]
  node_bytecode["Bytecode generation<br/>[engine.rs]"]
  node_vm["Register VM<br/>[machine.rs]"]
  node_native["Native backend<br/>[program.rs]"]
  node_runtime["Native runtime<br/>[lib.rs]"]
  node_host["Host integration<br/>[lib.rs]"]
end

subgraph group_user_features["User features"]
  node_formatter["Source formatter<br/>[formatter.rs]"]
  node_archive["Project packing<br/>[archive.rs]"]
  node_lsp["Language server<br/>[workspace.rs]"]
  node_debugger["Debugger<br/>[mod.rs]"]
  node_documentation["API documentation"]
end

node_developer(("Developer"))

node_developer -->|"invokes commands"| node_cli
node_cli -->|"resolves projects"| node_project
node_project -->|"discovers modules"| node_package
node_package -->|"enters checked compilation"| node_pipeline
node_pipeline -->|"lowers package"| node_hir
node_hir -->|"provides HIR"| node_typecheck
node_pipeline -->|"runs type checks"| node_typecheck
node_pipeline -->|"validates ownership"| node_ownership
node_developer -->|"formats source"| node_formatter
node_developer -->|"packs projects"| node_archive
node_developer -->|"uses editor services"| node_lsp
node_developer -->|"generates API docs"| node_documentation
node_pipeline -->|"feeds code generation"| node_construction
node_construction -->|"builds shared IR"| node_shared_ir
node_shared_ir -->|"lowers for VM"| node_bytecode
node_bytecode -.->|"executes bytecode"| node_vm
node_shared_ir -->|"prepares native program"| node_native
node_native -->|"links executable"| node_runtime
node_developer -->|"runs programs"| node_vm
node_developer -->|"builds native output"| node_native
node_host -.->|"provides host services"| node_runtime

click node_cli "https://github.com/jebailey/foster/blob/main/src/main.rs"
click node_project "https://github.com/jebailey/foster/blob/main/src/project.rs"
click node_package "https://github.com/jebailey/foster/blob/main/compiler/src/package.rs"
click node_lexer "https://github.com/jebailey/foster/blob/main/compiler/src/lexer.rs"
click node_parser "https://github.com/jebailey/foster/tree/main/compiler/src/parser"
click node_hir "https://github.com/jebailey/foster/blob/main/compiler/src/hir.rs"
click node_typecheck "https://github.com/jebailey/foster/tree/main/compiler/src/typecheck"
click node_ownership "https://github.com/jebailey/foster/tree/main/compiler/src/ownership"
click node_pipeline "https://github.com/jebailey/foster/blob/main/compiler/src/compiler/pipeline.rs"
click node_construction "https://github.com/jebailey/foster/blob/main/compiler/src/codegen/construction.rs"
click node_shared_ir "https://github.com/jebailey/foster/blob/main/compiler/src/codegen/shared.rs"
click node_bytecode "https://github.com/jebailey/foster/blob/main/bytecode/src/codegen/flow/engine.rs"
click node_vm "https://github.com/jebailey/foster/blob/main/vm/src/machine.rs"
click node_native "https://github.com/jebailey/foster/blob/main/compiler/src/native/program.rs"
click node_runtime "https://github.com/jebailey/foster/blob/main/runtime/src/lib.rs"
click node_host "https://github.com/jebailey/foster/blob/main/host/src/lib.rs"
click node_formatter "https://github.com/jebailey/foster/blob/main/src/formatter.rs"
click node_archive "https://github.com/jebailey/foster/blob/main/src/archive.rs"
click node_lsp "https://github.com/jebailey/foster/blob/main/src/lsp/workspace.rs"
click node_debugger "https://github.com/jebailey/foster/blob/main/src/debugger/mod.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_cli,node_project,node_package toneBlue
class node_lexer,node_parser,node_hir,node_typecheck,node_ownership,node_pipeline,node_construction,node_shared_ir toneAmber
class node_bytecode,node_vm,node_native,node_runtime,node_host toneMint
class node_formatter,node_archive,node_lsp,node_debugger,node_documentation toneRose
class node_developer toneIndigo
```

## Components

### Toolchain entry

- [Foster CLI](https://github.com/jebailey/foster/blob/main/src/main.rs): `src/main.rs`
- [Project handling](https://github.com/jebailey/foster/blob/main/src/project.rs): `src/project.rs`
- [Package modules](https://github.com/jebailey/foster/blob/main/compiler/src/package.rs): `compiler/src/package.rs`

### Language compiler

- [Lexer](https://github.com/jebailey/foster/blob/main/compiler/src/lexer.rs): `compiler/src/lexer.rs`
- [Parser and AST](https://github.com/jebailey/foster/tree/main/compiler/src/parser): `compiler/src/parser`
- [HIR lowering](https://github.com/jebailey/foster/blob/main/compiler/src/hir.rs): `compiler/src/hir.rs`
- [Type and effect checks](https://github.com/jebailey/foster/tree/main/compiler/src/typecheck): `compiler/src/typecheck`
- [Ownership checks](https://github.com/jebailey/foster/tree/main/compiler/src/ownership): `compiler/src/ownership`
- [Checked compilation](https://github.com/jebailey/foster/blob/main/compiler/src/compiler/pipeline.rs): `compiler/src/compiler/pipeline.rs`
- [IR construction](https://github.com/jebailey/foster/blob/main/compiler/src/codegen/construction.rs): `compiler/src/codegen/construction.rs`
- [Shared SSA and sealing](https://github.com/jebailey/foster/blob/main/compiler/src/codegen/shared.rs): `compiler/src/codegen/shared.rs`

### Execution backends

- [Bytecode generation](https://github.com/jebailey/foster/blob/main/bytecode/src/codegen/flow/engine.rs): `bytecode/src/codegen/flow/engine.rs`
- [Register VM](https://github.com/jebailey/foster/blob/main/vm/src/machine.rs): `vm/src/machine.rs`
- [Native backend](https://github.com/jebailey/foster/blob/main/compiler/src/native/program.rs): `compiler/src/native/program.rs`
- [Native runtime](https://github.com/jebailey/foster/blob/main/runtime/src/lib.rs): `runtime/src/lib.rs`
- [Host integration](https://github.com/jebailey/foster/blob/main/host/src/lib.rs): `host/src/lib.rs`

### User features

- [Source formatter](https://github.com/jebailey/foster/blob/main/src/formatter.rs): `src/formatter.rs`
- [Project packing](https://github.com/jebailey/foster/blob/main/src/archive.rs): `src/archive.rs`
- [Language server](https://github.com/jebailey/foster/blob/main/src/lsp/workspace.rs): `src/lsp/workspace.rs`
- [Debugger](https://github.com/jebailey/foster/blob/main/src/debugger/mod.rs): `src/debugger/mod.rs`
- **API documentation**

### Other components

- **Developer**

## Connections

- Developer → Foster CLI: invokes commands (evidence: `README.md`)
- Foster CLI → Project handling: resolves projects (evidence: `README.md`)
- Project handling → Package modules: discovers modules (evidence: `README.md`)
- Package modules → Checked compilation: enters checked compilation (evidence: `compiler/src/compiler/pipeline.rs`)
- Checked compilation → HIR lowering: lowers package (evidence: `compiler/src/compiler/pipeline.rs`)
- HIR lowering → Type and effect checks: provides HIR (evidence: `compiler/src/hir.rs`)
- Checked compilation → Type and effect checks: runs type checks (evidence: `compiler/src/compiler/pipeline.rs`)
- Checked compilation → Ownership checks: validates ownership (evidence: `compiler/src/compiler/pipeline.rs`)
- Developer → Source formatter: formats source (evidence: `README.md`)
- Developer → Project packing: packs projects (evidence: `README.md`)
- Developer → Language server: uses editor services (evidence: `README.md`)
- Developer → API documentation: generates API docs (evidence: `README.md`)
- Checked compilation → IR construction: feeds code generation
- IR construction → Shared SSA and sealing: builds shared IR (evidence: `compiler/src/codegen/program.rs`)
- Shared SSA and sealing → Bytecode generation: lowers for VM (evidence: `compiler/src/codegen/shared.rs`)
- Bytecode generation → Register VM: executes bytecode
- Shared SSA and sealing → Native backend: prepares native program (evidence: `compiler/src/native/program.rs`)
- Native backend → Native runtime: links executable (evidence: `compiler/src/native/program.rs`)
- Developer → Register VM: runs programs (evidence: `README.md`)
- Developer → Native backend: builds native output (evidence: `README.md`)
- Host integration → Native runtime: provides host services