Concepts

How the platform works in steady state. Pages here synthesize the current state of the system, not its history. For decision history, see the Architecture Decision Records (ADRs) in docs/decisions/.

Reading order for new readers

1. System overview — one page, one diagram, the whole platform. Start here.
2. Auth model — OAuth + M2M + Clerk + WorkOS, how they compose, who uses what.
3. Events — dual-bus pattern, outbox, at-least-once delivery.
4. Brands and multi-tenancy — brand_id everywhere.
5. Audit and PHI — append-only audit, safe-views, BAA gating.
6. Idempotency and retries — every retry is safe.
7. Durable workflows — multi-step business processes on Inngest.
8. Integration adapters — how we talk to external vendors.
9. Rate limits and circuit breakers — protecting the platform and its callers.
10. Zero-downtime migrations — expand–contract pattern.
11. Reliability and deployment — stages, rollback, SLOs.
12. Service architecture — per-service shape conventions.

Page shape

Every concept page follows the same structure:

• What this is — one sentence on what the concept covers
• Who it’s for — the audience that needs to read it
• What to read next — three related pages
• Body — diagrams, code examples, common mistakes
• See also — implementing services and related concepts
• Source ADRs — the decision records that established the design

Scope

Concept pages are not:

• Decision records. ADRs in docs/decisions/ capture moment-in-time decisions; concept pages describe the resulting steady state.
• Runbooks. Runbooks in docs/runbooks/ describe response procedures for incidents. Concept pages describe normal operation.
• API reference. Reference pages live under /reference/ and are generated from each service’s openapi.yaml.

Use a concept page to answer “how does X behave when Y happens.” Use a runbook to answer “I just got paged for X — what do I do.”