Architecture decisions
Short, dated records of structural decisions and why they were made. ADRs capture context that gets lost otherwise — they’re for the next engineer (or agent) who asks “why is it like this?”
Index
| # | Title | Status |
|---|---|---|
| 0001 | Nx monorepo, pnpm workspaces | Accepted |
| 0002 | Clerk for authentication | Accepted |
| 0003 | Drizzle ORM over Prisma / TypeORM | Accepted |
| 0004 | Multi-org isolation by organization_id, enforced in code | Accepted |
| 0005 | API-first; business logic lives in the API | Accepted |
| 0006 | Hebrew/RTL as a first-class language | Accepted |
| 0007 | R2 with separate compliance bucket | Accepted |
| 0008 | Platform tiers as the feature-gate primitive | Accepted |
| 0009 | Background jobs via BullMQ on Redis | Accepted |
| 0010 | Spotter agent architecture | Accepted (Phase 1 shipped) |
| 0011 | Native automations engine (FIT-157) | Proposed (spike / design only) |
| 0012 | Lead status model (configurable pipelines) + channel-agnostic inbox | Accepted (shipped) |
| 0013 | Lead messaging consent & opt-out (gate for lead automations, FIT-206) | Accepted |
| 0014 | Freeform-to-structured workout transformer (FIT-245) | Accepted |
| 0015 | Arbox parity mode (“Arbox Bridge”) — migration parity + Move middleman (FIT-258) | Proposed (design spike) |
| 0016 | Plan change, booking-entitlement sweep, and manual charges (FIT-254) | Accepted |
| 0017 | Fizikal as the FreeFit/Move rails vendor (FIT-65) | Proposed (probe-gated) |
| 0018 | Org-scoped audit logging — app-level capture, 24-month retention (FIT-20) | Accepted |
Writing a new ADR
Use the next free number. Keep it short — under 200 lines. Include:
- Context — what triggered the decision.
- Decision — what we picked.
- Consequences — positive AND negative. Be honest about the costs.
- Alternatives considered — what else was on the table and why we rejected it.
- Related — links to other ADRs / runbooks / feature docs.
When superseding an older ADR, link forward AND back, and update its Status: to Superseded by ADR-NNNN.