Conventions & State Management

​

State Management with Riverpod

​

Architecture

• UI / Presentation: Flutter widgets/screens and feature ViewModels. Exposes UI state and dispatches user actions.
• Application: Command and query actions (one class per operation).
• Domain: Pure models and abstract repository contracts.
• Data / Persistence: Drift repository implementations.

​

Application Actions

• One class per operation.
• Verb-phrase class names (e.g. CreateTask).
• No UseCase suffix.
• call(...) API with named parameters.
• All actions include privacy-safe diagnostics logging.
• Futures return ApplicationResult<T> (Success<T> / Failure<T>).

• Mutation actions log info on start/success.
• Read and compute actions log debug on start/success.
• Watch actions log debug when a subscription starts and when it terminates.
• Validation / not-found / conflict failures log warning.
• Unexpected / infrastructure failures log error.
• Logs must include metadata only: IDs, counts, date windows, and filter presence.
• Logs must never include task titles, raw event payloads, or raw check-in text values (body / mind / mood contents).

• CreateTask
• SaveCheckIn
• GetEventsInWindow

​

Repository Contracts

• No write DTO classes in repository interfaces.
• Field-level partial updates use FieldUpdate<T>.
• Repository adapters in core/persistence/ handle schema mappings, transactions, and event triggers.

​

Provider Wiring

​

Core / Bootstrap Providers

• repository_providers.dart: Instantiates the concrete Drift repositories.
• logger_provider.dart: Global diagnostic logs.
• Feature action providers (e.g. task_actions_providers.dart, mana_actions_providers.dart): One provider per application action class.

​

Feature Providers & ViewModels

part 'home_providers.g.dart';

@riverpod
Future<HomeViewData> homeView(Ref ref) async {
  // Watch or read actions to fetch domain data
}

​

ViewModel Conventions

• Commands are methods on the ViewModel class.
• Commands return Future<ApplicationResult<T>>.
• ViewModels read action providers, never database/repository providers directly.

​

Folder Layout

lib/
  ├── core/                             # Shared infrastructure
  │   ├── bootstrap/
  │   │   └── providers/                # Action bindings & singletons
  │   ├── design/                       # Tokens & primitives
  │   ├── diagnostics/                  # Logging wrappers
  │   ├── domain/                       # Core models & repositories
  │   ├── persistence/                  # Drift tables & DB repositories
  │   └── platform/                     # Platform wrappers
  │
  └── features/                         # Feature slices
      └── <feature>/
          ├── domain/                   # Local models & policies
          ├── application/              # Local actions
          └── presentation/             # Presentation layer
              ├── view_models/          # Riverpod state notifier ViewModels
              ├── providers/            # Generated UI providers
              └── widgets/              # UI widgets and screens

​

Naming

​

Async Patterns

• Reactive reads: StreamProvider + watch actions (e.g., taskListProvider).
• Point-in-time reads/writes: Future + ApplicationResult<T>.
• No raw Drift query exposure above data adapters.
• Every async state consumed in widgets must explicitly handle loading, error, and data states.