Architecture Decision Records
Architecture Decision Records (ADRs) capture the key technical decisions made during the design and development of SALLY. Each record documents the context that motivated a decision, the decision itself, and the consequences — what became easier and what became harder as a result.
ADRs serve as a historical record for the engineering team. When someone asks “why did we choose X over Y?”, the answer is in the ADR.
Index
| ADR | Title | Status | Date | Summary |
|---|---|---|---|---|
| 001 | Monorepo with Turborepo | Accepted | February 2026 | Single repository with Turborepo and pnpm workspaces for shared types and coordinated builds |
| 002 | NestJS over Express | Accepted | February 2026 | Structured backend framework with modules, dependency injection, and guards |
| 003 | Firebase Auth + JWT | Accepted | February 2026 | Firebase for identity management, custom JWT for API authorization with role and tenant claims |
| 004 | Multi-tenant Row Isolation | Accepted | February 2026 | Single database with row-level tenant isolation via tenantId foreign key |
| 005 | Domain-Driven Modules | Accepted | February 2026 | Backend organized into domain modules (Fleet, Operations, Routing, Integrations, Platform) |
| 006 | Shadcn + Dark Theme First | Accepted | February 2026 | Copy-paste component library with mandatory dark theme and grayscale-only palette |
| 007 | Real-time Communication with Socket.IO | Accepted | February 2026 | SSE for server push and Socket.IO WebSocket for bidirectional dispatcher-driver messaging |
| 008 | Multi-channel Notification Delivery | Accepted | February 2026 | Email via Resend, SMS via Twilio, browser push via Web Push API, and in-app notifications |
ADR Format
Each ADR follows a consistent structure:
- Status — Whether the decision is Proposed, Accepted, Deprecated, or Superseded.
- Context — The problem or situation that motivated the decision.
- Decision — What was decided and why.
- Consequences — The trade-offs: what became easier and what became harder.
New ADRs are numbered sequentially. Once accepted, an ADR is not modified unless it is superseded by a later decision, in which case the original ADR is updated with a link to its replacement.