ADR-0003: MVVM + Repository + Use Case layering

Context

To keep the codebase maintainable, testable, and clear in responsibilities, we need a well-defined architectural layering approach for UI, business logic, and data access.

Decision

We will adopt the following layering for the app:

• UI layer: Jetpack Compose + ViewModels (MVVM). ViewModels own UI state and presentation logic.
• Domain layer: Use Cases (interactors) encapsulating single business operations and orchestration.
• Data layer: Repositories that provide data from Room and other sources, exposing simple interfaces consumed by Use Cases.

Boundaries:

• ViewModels should call Use Cases only; they should not call Repositories or DAOs directly.
• Repositories expose domain-friendly models and map persistence entities as needed.

Rationale

• Separation of concerns improves testability and evolution of each layer.
• Use Cases centralize business rules and make them easier to reuse across UI surfaces.
• Repositories abstract persistence and make future changes (e.g., adding sync) less invasive.

Consequences

• Positive:

  • Clear testing targets for unit and integration tests.
  • Easier to reason about responsibilities and side effects.

• Downsides:

  • Additional boilerplate and indirection.
  • Slightly longer ramp for contributors unfamiliar with the pattern.

Follow-up work:

• Create lightweight templates/examples for each layer to speed developer onboarding.
• Document mapping rules between persistence entities and domain models.

Alternatives Considered

• Single ViewModel-per-screen owning Repositories directly — rejected for future extensibility reasons.