Architecture · LikeC4

Gas City

Orchestration-builder SDK: a controller loop that reconciles desired config to running agents and drives formula bead-graphs to completion

Open the interactive explorer → View on GitHub

built evolving planned research risk

The whole picture

System landscape

The system in context, then opened up into its containers.

Gas City — system landscape — Gas City — system landscape
index

Gas City — containers (built vs evolving vs planned) — Gas City — containers (built vs evolving vs planned)
gascitySystem

Orchestration-builder SDK: a controller loop that reconciles desired config to running agents and drives formula bead-graphs to completion

Risks & open questions — Risks & open questions
risks

Planned & research work — Planned & research work
planned

Inside each box

Containers & components

Each part decomposed into the components that implement it. Every box links to its source in the interactive explorer.

Controller runtime — components — Controller runtime — components
controllerContainer

The per-city reconciliation loop: config watch → reconcile sessions → pool scaling → wisp GC → order dispatch → graph dispatch. Implemented as functions in cmd/gc/, not a standalone package

Dispatch & graph execution — components — Dispatch & graph execution — components
dispatchContainer

Sling kicks off a run (compile formula → materialize bead graph → route → nudge); the control dispatcher then drives the v2 graph to completion via control beads

Formulas & molecules — components — Formulas & molecules — components
formulaContainer

Formula = a written-down method (TOML). Compile → flat graph (v2) or molecule (v1 single-agent sequence). A formula is the method; the beads are the work

Bead store — interface & backends — Bead store — interface & backends
beadsContainer

The work spine: everything is a bead (task, mail, session, convoy, molecule), differing only by type, behind one Store interface. The loop closes through this shared state, so work survives a crash on either side

Session & runtime providers — components — Session & runtime providers — components
runtimeContainer

Start/stop/prompt/observe sessions regardless of engine. The SDK manages session lifecycle; the prompt defines behavior — these concerns never cross

Config & packs — components — Config & packs — components
configContainer

city.toml schema + progressive activation (Levels 0–8 by section presence) + multi-layer override resolution. Pack config IS the feature flag; the City is the local (root) pack

Orders & GitHub monitor — components — Orders & GitHub monitor — components
ordersContainer

An Order automates WHEN a formula runs: a trigger (cooldown/cron/condition/event/manual) paired with the formula to fire. Health Patrol is one kind of order

HTTP + SSE API — components — HTTP + SSE API — components
apiContainer

Every endpoint registered through Huma against annotated Go types → generated OpenAPI 3.1. The CLI and API are two typed projections over one canonical domain; long-running mutations return 202 + a request.result event

How it runs

Walkthrough flows

Dynamic views — the narrative spine of the system, step by step.

Walkthrough — one controller reconciliation tick — Walkthrough — one controller reconciliation tick
controllerTick

Each tick (default 30s, or on config-dirty edge): reload config if changed, rebuild the desired agent set (pool scale_checks run in parallel), converge sessions, GC wisps, and dispatch due orders.

Walkthrough — sling a formula → graph drives to completion — Walkthrough — sling a formula → graph drives to completion
slingFormula

Sling kicks off the run; the control dispatcher then drives the v2 graph outside any session — gating, fanning out, retrying, and draining via control beads.

Walkthrough — an agent claims and works a bead — Walkthrough — an agent claims and works a bead
workBead

The loop closes through shared bead-store state: the controller spawns sessions but reads progress from the store and event bus, which is why work survives a crash on either side.

Walkthrough — an order fires a formula — Walkthrough — an order fires a formula
orderFires

An Order automates WHEN a formula runs. Event-triggered orders read the event stream to decide; the same notifications humans watch can drive the fleet — no specific agent role required.

Where it runs

Deployment

What runs where, and the process & data boundaries between the pieces.

Deployment — where each piece runs — Deployment — where each piece runs
deployment

Explore it live

The figures above are static exports. The interactive explorer lets you pan, zoom, follow relationships, and jump from any box to the source.

Open the interactive explorer →