Skip to content

1. use riverpod for state management

status

accepted

context

the app has many independent, cross-cutting concerns (meditation editing, playback, history, sync, notifications, health integration, theming) that need testable, compile-safe state management and dependency injection across mobile, desktop, and (later) Wear OS targets.

decision

use flutter_riverpod + riverpod_annotation/riverpod_generator (3.x) as the app's sole state-management/DI mechanism. providers are colocated with the feature or repository they belong to, generated via @riverpod/ @Riverpod(keepAlive: true) annotations rather than hand-written.

alternatives considered

  • bloc: more explicit event/state boilerplate; a reasonable choice for larger teams but more ceremony than needed for a solo developer.
  • provider: simpler, but weaker for the number of cross-cutting, independently-testable concerns this app has.

consequences

  • every service/repository the UI depends on should be exposed via a provider, making it trivial to override with a fake in tests (see test/app_test.dart for the pattern of overriding appDatabaseProvider with an in-memory database).
  • riverpod 3.x was used instead of 2.x since it was the current stable release at implementation time; see the "Implementation log" appendix in docs/dev-guide/PROJECT_PLAN.md for version-pinning details.