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) |
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.