ADR-0001: Local Data Engine and Migration Strategy

• Status: Accepted
• Date: 2026-04-10

Context — ADR-0002

The application is backend-primary with offline resilience via IndexedDB fallback. It must support offline writes, immutable event history, and queued sync operations. The storage layer must be browser-compatible and maintainable for contributors.

Decision — ADR-0002

Use IndexedDB as the canonical client storage engine with a typed repository layer built through Dexie.

Adopt explicit schema versioning and forward-only migrations.

Migration rules:

• all schema changes must define a migration step
• migrations must be idempotent and testable
• destructive migrations are not allowed without compatibility fallback
• event stores remain append-only except sync-state fields

Consequences — ADR-0002

Benefits:

• reliable offline persistence in browser environments
• clear upgrade path as entities evolve
• maintainable abstraction over raw IndexedDB APIs

Tradeoffs:

• migration discipline is required for every schema change
• contributors must test upgrades from prior versions

Alternatives Considered — ADR-0002

• raw IndexedDB only: rejected for developer ergonomics and migration complexity
• localStorage/sessionStorage: rejected for capacity and transactional limitations
• WebSQL: rejected because it is not a viable cross-browser baseline

References — ADR-0002

• ../../product/prd.md
• ../srs.md
• ../sdd.md
• ../../reference/data-dictionary.md
• Requirement IDs: FR-013, FR-014, NFR-005, NFR-012, DR-004, SR-001