Architecture Documentation
Current-state documentation for Gas City’s subsystems. Each document describes how the subsystem works today, not how we wish it worked. For proposed changes, write a design doc indocs/design/.
Reading Order
Start with the overview, then dive into the subsystem you need.Foundation
- Glossary — authoritative definitions of all terms
- Nine Concepts Overview — the 5 primitives + 4 derived mechanisms that compose Gas City
Layer 0-1: Primitives
These are irreducible. Removing any makes it impossible to build a multi-agent orchestration system.- Bead Store — universal persistence substrate for all work units (tasks, mail, molecules, convoys)
- Event Bus — append-only pub/sub log of all system activity
- Config System — TOML loading, progressive activation, multi-layer override resolution
- Agent Protocol — agent lifecycle backed by session providers (tmux, subprocess, k8s)
- Prompt Templates — Go
text/templatein Markdown defining role behavior
Layer 2-4: Derived Mechanisms
Each is provably composable from the primitives.- Messaging — inter-agent mail via beads + nudge via agent protocol
- Formulas & Molecules — work definitions (TOML) and their runtime instances (bead trees)
- Dispatch — sling: agent selection + formula instantiation + convoy creation
- Health Patrol — supervision model, reconciliation, crash tracking, idle detection
Infrastructure
- Controller — the main loop: config watch, reconciliation tick, order dispatch
- Orders — gate-conditioned formula/exec dispatch, rig-scoped labels
End-to-End Traces
These trace a concrete operation through all layers. The most effective way to understand how the system fits together.- Life of a Bead — create → hook → claim → execute → close
- Life of a Molecule — formula parse → dispatch → molecule create → step execution → completion
Document Types
Gas City uses four document types (following CockroachDB’s tech-note / RFC distinction):| Type | Directory | Purpose | Lifecycle |
|---|---|---|---|
| Architecture doc | docs/architecture/ | How it works now | Living; update when code changes |
| Design doc | docs/design/ | How we want it to work | Proposal → accepted → implemented → obsolete |
| Reference doc | docs/reference/ | Exhaustive lookup (CLI, config, API) | Must stay in sync; partially generated |
| Tutorial | docs/tutorials/ | Learning path with exercises | Ordered progression |
Conventions
- Code references use repo-relative paths:
internal/beads/store.go - Cross-references use descriptive link text explaining why you’d follow the link
- No role names in examples — Gas City has zero hardcoded roles
- Invariants are stated as testable assertions
- Update date at the top of each doc tracks when it was last verified against code