Skip to main content

Flows

Prose and Mermaid sequence diagrams describing how data and control move through the system for specific scenarios. Flows are step-by-step narratives — they answer "what happens when X?" rather than "what does the system look like?".

What belongs here​

  • Request/response lifecycle across multiple services (e.g. sign-in flow, room join flow, recording flow)
  • Event-driven sequences (e.g. WorkOS webhook → eventsync worker → database)
  • Cross-system data flows that involve more than one repo

What belongs in ../diagrams/ instead​

Static topology diagrams showing how components relate to each other — infrastructure maps, service dependency graphs, deployment layouts. These are rendered as D2 .svg files.

Format​

Flows are written in Markdown with embedded Mermaid sequence diagrams where helpful. No D2 files here — D2 is for topology, Mermaid sequenceDiagram is for flows.