Switchain Services — System Documentation
Entry point for describing the running system (contexts, states, events, flows, integrations). Rules and coding standards live in docs/conventions/ — this tree is for describing what the system is and does.
Canonical rule: everything descriptive lives under docs/system/. packages/ stays pure code.
Progressive disclosure
Three hops max from any question to its answer:
- Level 0 (this page) — global index of tables with links.
- Level 1 — overview of a context, app, or section.
- Level 2 — detail, self-contained (one state machine, one flow, one runbook).
Catalogs
System-level topics
- Architecture (C4) — context, containers, components, code diagrams.
- External integrations — CEXes, blockchains, providers.
- Runbooks — operational scenarios and setup guides.
- Glossary — domain terminology.
Predictable paths
| Document | Path |
|---|---|
| Context overview | docs/system/contexts/<ctx>/readme.md |
| Events for a context | docs/system/contexts/<ctx>/events.md |
| State machine | docs/system/state-machines/<slug>.md |
| App overview | docs/system/apps/<app>/readme.md |
| Cross-context flow | docs/system/events/flows/<slug>.md |
| Runbook | docs/system/runbooks/<slug>.md |
| External integration | docs/system/integrations/<kind>/<name>.md |
Slugs are always kebab-case of the enum, entity, or app name as it appears in TypeScript.
Templates
Document templates live in _templates/. The create-doc skill routes new system docs to the matching template.