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-0001
<problem statement and constraints>
### Decision — ADR-0001
<what was chosen>
### Consequences — ADR-0001
<tradeoffs and expected impact>
### Alternatives Considered — ADR-0001
<option 1, option 2, option 3>
### References — ADR-0001
- ../../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 — Permissões com Escopo por Entidade | Proposed | 2026-06-26 |
| ADR-0021 | EntityRepository — Persistence Abstraction for Worker Services | Accepted | 2026-07-04 |
| ADR-0022 | Multi-Role User Support — roles[], user_roles, and AuthPrincipal | Accepted | 2026-07-05 |
| ADR-0023 | Server-Authoritative Model — Command Handler Único + Events como Auditoria | Proposed | 2026-07-07 |
| ADR-0024-unified-error-handling.md | Unified Error Handling — Centralized ErrorCode Registry | Accepted | 2026-07-11 |
| ADR-0025-onboarding-subdomain.md | Onboarding Subdomain — Two Vite Configs vs Separate Project | Accepted | 2026-07-13 |
| ADR-0026-deterministic-daily-codes.md | Deterministic Daily Codes for Offline Check-in/Check-out | Accepted | 2026-07-16 |
| ADR-0027-read-mutation-hooks.md | Two-Hook Read/Mutation Pattern for UI Data Access | Accepted | 2026-07-23 |
| ADR-0028-persistence-pattern-boundaries.md | Persistence Pattern Boundaries — Three Legitimate Strategies | Accepted | 2026-07-23 |
| ADR-0029-amend-adr-0023.md | ADR-0023 Amendment — CommandContext, Proxy Governance, and Enforcement | Proposed | 2026-07-25 |
| ADR-0030-dexie-reversion.md | Dexie Reversion — 8 Key Design Decisions (issue #510) | Accepted | 2026-07-25 |
| ADR-0031-two-pass-pbkdf2.md | Two-Pass PBKDF2 for Free-Tier Password Security | Proposed | 2026-07-28 |
| ADR-0032-durable-objects-fan-out.md | Durable Objects for Real-Time Event Fan-Out | Accepted | 2026-07-29 |
| ADR-0033-mcp-surface.md | MCP Surface — Agent Integration via Model Context Protocol | Proposed | 2026-07-31 |
| ADR-0034-class-session-relationship.md | Class–Session Relationship in Check-in/Capacity Queries | Accepted | 2026-08-05 |