Architecture Decision Record Log
Purpose
This file tracks architecture decisions that affect implementation across modules.
Use ADR entries to avoid implicit decisions and reduce design drift.
Status Values
- Proposed
- Accepted
- Superseded
- Deprecated
ADR Format
Each entry should include:
- ID:
ADR-XXXX - Title
- Status
- Date
- Context
- Decision
- Consequences
- Alternatives Considered
- References to PRD, SRS, SDD, and requirement IDs
Template
md
## ADR-XXXX: <Title>
- Status: Proposed | Accepted | Superseded | Deprecated
- Date: YYYY-MM-DD
### Context — ADR-XXXX
<problem statement and constraints>
### Decision — ADR-XXXX
<what was chosen>
### Consequences — ADR-XXXX
<tradeoffs and expected impact>
### Alternatives Considered — ADR-XXXX
<option 1, option 2, option 3>
### References — ADR-XXXX
- ../../product/prd.md
- ../srs.md
- ../sdd.md
- Requirement IDs: FR-..., NFR-..., SR-..., SCR-...Working Rules
- A new architecture-impacting PR should include an ADR update when needed.
- Mark old ADRs as superseded instead of deleting history.
- Keep ADR decisions implementation-ready and testable.
- Link ADR decisions to RTM.csv when requirements or coverage are affected.
Accepted ADRs
| ID | Title | Status | Date |
|---|---|---|---|
| ADR-0001 | Local Data Engine and Migration Strategy | Accepted | 2026-04-10 |
| ADR-0002 | Sync Transport, Ordering, and Idempotency | Accepted | 2026-04-10 |
| ADR-0003 | Auth Adapter and Session Token Model | Accepted | 2026-04-10 |
| ADR-0004 | Client-side encryption approach for sensitive local data | Accepted | 2026-04-11 |
| ADR-0005 | Deterministic conflict ordering details | Accepted | 2026-04-11 |
| ADR-0006 | Service-worker cache invalidation strategy | Accepted | 2026-04-11 |
| ADR-0007 | Keycloak token validation boundary | Accepted | 2026-04-11 |
| ADR-0008 | Backend schema and idempotency ledger baseline | Accepted | 2026-04-11 |
| ADR-0009 | Debian + Docker Compose deployment baseline | Accepted | 2026-04-11 |
| ADR-0010 | Backup and restore policy | Accepted | 2026-04-11 |
| ADR-0011 | Phase 2 user-management backend alignment | Accepted | 2026-04-11 |
| ADR-0012 | Photo/media policy | Accepted | 2026-04-11 |
| ADR-0013 | Pagination strategy | Accepted | 2026-04-11 |
| ADR-0014 | Open Core architecture — plugin-based modules | Accepted | 2026-07-03 |
| ADR-0015 | Code Quality Tooling — ESLint + Prettier | Superseded | 2026-06-20 |
| ADR-0016 | RBAC Scope System — Entity-Scoped Permissions | Accepted | 2026-06-26 |
| ADR-0017 | Migration Strategy (Dexie → SQLite WASM) | Accepted | 2026-06-29 |
| ADR-0018 | Design System Architecture — Tokens, Themes, Tooling | Accepted | 2026-06-27 |
| ADR-0019 | Runtime Theme Switching — data-theme, Hook, Custom Themes | Accepted | 2026-06-27 |
| ADR-0020 | SSE Feed: D1 Polling over In-Memory Pool | Accepted | 2026-06-28 |
| ADR-0021 | EntityRepository — Persistence Abstraction for Workers | Accepted | 2026-07-04 |
| ADR-0022 | Multi-Role User Support — roles[], user_roles, AuthPrincipal | Accepted | 2026-07-05 |
Only ADRs with an English translation are linked here. The remaining ADRs are available in Portuguese at the root of the portal.