#Jam architecture atlas
On this page
ChaptersSubsystem chaptersHow to read a claimDiagramsGenerated referenceInteractive reportScopeThis atlas describes how Jam works on main: what runs, who owns each piece of state, how requests and events move, and where the system recovers from failure. It is written for engineers who change the system, and in particular for the refactor that aims to make new coding-agent harnesses and features pluggable without breaking the contracts and core behaviors listed here.
Start with ARCHITECTURE.md at the repository root. It gives the bird's-eye view, the codemap, and reading paths. This directory holds the detail.
#Chapters
| Chapter | Question it answers |
|---|---|
| 01 Context and boundaries | What is Jam, what does it talk to, and where are the trust boundaries? |
| 02 Runtime topology | Which processes run, who starts and stops them, and how do they communicate? |
| 03 Domain and authority | What are identities, sessions, hosts, and rooms, and who owns each fact? |
| 04 Consistency and recovery | What survives a crash, what is replayed, and in what order does the daemon come back? |
| 05 Key flows | How do assignment, messaging, agent turns, collaboration, and restart work end to end? |
| State machines | Which lifecycles exist, who drives each transition, and where is the state stored? |
| Subsystems | How each major area works internally. |
| Extension seams | What adding a harness or feature touches today. |
| Future directions | Which refactor directions exist for each area, how they compare, and which one is recommended. |
| Documentation drift | Which statements in AGENTS.md, docs, and comments disagree with the code. |
| Generated reference | Complete inventories of the API, events, schema, and crate graph. |
#Subsystem chapters
How the seven subsystems depend on each other. An arrow points from a subsystem to one it calls or reads.
| Chapter | Scope |
|---|---|
| Messaging and room state | Band transport, inbound delivery pipeline, durable queues, outbound send, room feed, event fan-out |
| Execution and lifecycle | Peers, workers, host sessions, runtime templates, runtime hosts, configuration transactions |
| Providers and attached agents | The Host seam, every adapter, provider protocols, runtime tools, capability matrix |
| Sandbox, workspaces, and continuity | Docker Sandbox lifecycle, managed workspaces, provider checkpoints, archive and cleanup |
| Tasks, questions, plans, and artifacts | Private lanes, shared board, questions, permissions, attention, plans, artifacts |
| Usage, analytics, accounts, and discovery | Usage and cost pipeline, product analytics, sign-in and accounts, Nearby discovery |
| Clients, packaging, and updates | Desktop app and its state model, CLI, Band peer plugin, bundles, updater |
#How to read a claim
Claims that matter for a refactor carry evidence. The atlas uses four evidence classes:
| Class | Meaning | Example citation |
|---|---|---|
| Code | Read in the implementation on main |
crates/jam-manager/src/fanout.rs, Fanout::publish |
| Test | A named test asserts the behavior | lifecycle.rs::rebuild_replays_persisted_continuity_reset_before_starting_workers |
| Runtime | Observed in a running build | Only where stated, with the build and platform |
| Inferred | Reasoned from code but not directly asserted anywhere | Marked Inferred in the text |
Citations name files and symbols rather than line numbers, because line numbers drift. Search for the symbol. Unmarked descriptive text summarizes code that the chapter cites nearby.
Invariants are stated as three parts when the difference matters: the rule, what enforces it (a type, a lock, a test, a CI guard), and any known exception.
#Diagrams
Diagrams are Mermaid blocks in Markdown and render directly in GitHub and most editors. node scripts/architecture/check-diagrams.mjs parses every block with the Mermaid version the desktop app pins and fails on syntax errors.
Hand-drawn diagrams follow these size limits so they stay readable at normal page width:
| Diagram | Target size |
|---|---|
| Structure (flowchart) | 8–15 nodes, split above about 20 |
| Sequence | 5–8 participants, 15–25 messages |
| State machine | 6–12 states |
| Entity-relationship | 8–12 entities per slice |
Each diagram has a one-line caption above it naming what it shows. Sequence diagrams mark durable commit points with a Note so a reader can see where a crash changes the outcome.
#Generated reference
node scripts/architecture/generate-reference.mjs (or just architecture-docs) regenerates reference/generated/ from source:
control-api.md: everyControlmethod and the daemon route, Tauri command, and CLI use that reach it.events.md: every daemon event kind and whether the desktop handles it.store-schema.md: all SQLite tables grouped by domain, with ERDs and the migration order.crates.md: the workspace dependency graph for the desktop, the thin CLI, and the daemon.metrics.md: size, churn hotspots, and provider-knowledge spread, with the charts underdiagrams/generated/.atlas-data.json: every value above in one file, which the interactive report reads.
The same command writes assessment/future-directions.md from scripts/architecture/directions.mjs. Edit the options there, not in the Markdown.
#Interactive report
just architecture-site builds a multi-page HTML version of the atlas into target/architecture-site/. Open target/architecture-site/index.html in a browser. It needs no server and no network connection.
The report adds what Markdown cannot do:
- A dashboard of the codebase numbers.
- An API explorer that filters all
Controlmethods by area, client, route kind, and required or default. - A crate graph that shows the closure of each binary and highlights a crate's dependencies and dependents.
- A schema explorer with every table's columns and allowed state values.
- A hotspot chart that links each file to GitHub.
- A gallery of every hand-drawn diagram, with full-screen pan and zoom on every diagram in the atlas.
- A direction picker that composes one refactor option per area, re-scores it under adjustable weights, flags unmet dependencies, orders the work into waves, and exports a decision record. The same data generates Future directions, so the two never disagree.
The build copies Mermaid, D3, and Cytoscape from apps/desktop/node_modules, so run pnpm --dir apps/desktop install first.
Run just architecture-docs-check to fail when the committed copy is stale or a diagram does not parse. The generated pages list what exists. The chapters explain what it means.
#Scope
The atlas describes the main branch. Behavior behind an experiment flag is labeled with the flag key. Legacy paths that still exist in code are described and labeled legacy, because a refactor must either preserve or explicitly remove them.
The atlas does not replace these documents:
AGENTS.mdand the scopedAGENTS.mdfiles are the rules for changing the code.docs/internals/holds implementation notes for authentication and runtime features.docs/user-guide.mdanddocs/advanced-reference.mddescribe the product for users.
Where those documents already explain a mechanism in depth, the atlas summarizes it and links there.