ADR-0004: Room as persistence mechanism

Context

The app requires a local relational persistence layer for structured user data: inbox items, processed items, reflections, syntheses and user vision data. The Android ecosystem offers several options; Room is a common, well-supported choice that integrates with Jetpack and Hilt.

Decision

We will use Room as the primary local persistence mechanism for the project.

Scope boundaries:

• Room will host the canonical on-device database for all domain entities.
• Schema versioning and migrations are required and must be part of any change touching entities.

Rationale

• Tight integration with Jetpack components (LiveData/Flow, Kotlin Coroutines).
• Compile-time query validation and generated DAOs reduce runtime errors.
• Well-understood migration and tooling support in Android ecosystem.

Consequences

• Positive:

  • Faster development with less plumbing for SQL access.
  • Better tooling and developer productivity.

• Downsides:

  • Tied to Android platform; migration to other platforms requires rework.
  • Potential complexity around migrations and multi-threaded access.

Follow-up work:

• Define a clear migration policy and automated tests for migrations.
• Investigate optional on-disk encryption strategies for sensitive fields.

Alternatives Considered

• Raw SQLite — rejected for verbosity and maintenance cost.
• Key-value stores (DataStore) — rejected because structured queries and relations are needed.