This repo spans a Go daemon, two Bun runtimes, half a dozen pnpm apps, and four shared TypeScript packages. When a new contributor asks "what happens when a user creates a document?", the honest answer is "let me trace it across nine files and three protocols and get back to you." That answer is fine once. It is exhausting on the tenth telling.
So we built a single-page HTML doc that draws every workspace as a graph and lets you click an action like Publish a document or Vault session key delegation and watch the call path light up across packages.
It lives at https://seed-flows.surge.sh
What it does
16 nodes — every top-level workspace plus peer and browser as external actors.
16 flows grouped into four categories: Documents, Identity & Capabilities, Discovery & Sync, Notifications.
Each flow is a list of steps. Every step records from → to, the protocol used (gRPC, IPC, libp2p, SMTP, OAuth-redirect, etc.), the payload shape, and a one-line note pointing at the relevant code path.
Click a flow → edges highlight, side panel shows the ordered steps.
Click Play → steps replay one-by-one, ~1.2s apart.
Click any node in the graph → sidebar filters to flows touching that package.
Search filters by flow name or summary.
How it's built
One HTML file. Cytoscape.js loaded from a CDN handles graph rendering and edge highlighting. All flow data lives in an inline <script type="application/json"> block, so adding a new flow means editing JSON, not code. Schema:
{
"id": "create-document",
"label": "Create new document",
"category": "Documents",
"summary": "…",
"steps": [
{
"from": "desktop",
"to": "backend",
"protocol": "gRPC",
"label": "Documents.CreateDocumentChange",
"payload": "{account, path, baseVersion, changes[], …}",
"notes": "backend/api/documents/v3alpha/documents.go handles signing + CRDT apply."
}
]
}
That's the entire authoring surface. JSON edit, reload, done.
How the flows were sourced
Bootstrapping the JSON took a research pass through the codebase: tracing each user action from its UI entry point through hooks, IPC, gRPC, storage, and out to peers or email transports. Several flows already had design docs in docs/; those acted as guard rails. Others were traced live by following imports and proto definitions. Each step records the file paths it walked through so the doc stays auditable — if a reader doubts a step, the citation is right there.
Why this is interesting
Architecture docs rot the moment someone renames a file. This visualizer rots too, but it concentrates the rot in one place: a JSON blob you can diff. The graph topology and rendering logic stays stable; only the prose changes.
It also acts as a forcing function. Writing a flow surfaced two real gaps in the codebase — a partial invite-redemption handler, and a search RPC that's still being wired up. Both got TODO: notes inline. The next person to fix them now has a checklist sitting in the doc.
What's next
Easy wins from here:
Extract the JSON into its own file once the doc gets big enough to warrant fetch() over an inline blob.
Add per-node prose (which subdirectories live where, what the package's job is).
Generate part of the JSON from the proto files instead of hand-curating, so the gRPC steps stay in sync automatically.
Embed the page in the existing @shm/docs site so it's reachable without a clone.
But none of that is required for the doc to be useful today. It already is.
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime