This directory is the single source of truth for what Reflex is, why it exists, and how it is built. Everything here was designed up front, before the first engine commit — read these docs first, then write code against them.
| # | Doc | What it answers |
|---|---|---|
| 01 | vision | What is this? Why does it exist? What is deliberately not in scope? |
| 02 | architecture | The high-level system: components, data flow, trigger classes |
| 03 | data-model | The schema every component reads and writes — the anchor |
| 04 | execution-engine | How a run actually executes: claim, retry, idempotency, reaper |
| 05 | observability-and-replay | The differentiator: traces, the UI, replay semantics |
| 06 | api-and-auth | Every endpoint, the auth model, webhook signatures |
| 07 | decisions | The trade-offs we already made and why — read before revisiting any design |
| 08 | scaling | How and when the system scales, and what it scaffolds into |
| 09 | roadmap | Build order, milestones, definition of done |
Everything in these docs is design, not implementation. The monorepo scaffold (Turborepo + Next.js shells) exists; the engine, worker, data model, and API do not. The roadmap in 09 is the contract for what gets built next.
- The queue is a delivery mechanism. The DB is the source of truth. Every reliability argument in these docs follows from that sentence.
- Runs are immutable history. Replays create new runs; original runs are never mutated.
- Every schema/API decision exists because the trace UI or a third party needs it — nothing decorative.
- Root README — position, one-paragraph pitch, quick start.
packages/integrations(planned) — the registry of trigger/action definitions this docs set describes.