App Architecture

​

Why This Architecture Exists

• Local-first reliability: core workflows must work offline.
• Deterministic business logic: same inputs should produce the same domain outputs.
• Replaceable infrastructure: database, logging, and integration details should be swappable.
• Low-coupling UI: widgets should render state and send intents, not run business rules.

​

Layer Model & Feature Slices

1. core/: shared infrastructure (bootstrap, design tokens/primitives, persistence database, diagnostics logging, notifications, shell routing, and utilities).
2. features/: self-contained slices representing distinct business concerns (home, mana, tasks, check_ins, orchard, insights, onboarding, settings, profile).

• Presentation: Render views (Widgets) and expose state (ViewModels/Providers).
• Application: Single-use action classes that execute workflows.
• Domain: Pure business models, rules, and local repository contracts.

[!NOTE] Local feature domain code is the dependency target within each slice. It must not import from presentation, widgets, or persistence/Drift libraries.

​

Directory Responsibilities

app/lib/
  ├── core/                     # Shared cross-cutting concerns
  │   ├── bootstrap/            # Startup overrides and global Riverpod wiring
  │   ├── design/               # Shared design primitives (AppButton, AppCard)
  │   ├── diagnostics/          # Diagnostics and logging interfaces (AppDiagnostics)
  │   ├── domain/               # Reusable models & repository interfaces
  │   ├── persistence/          # Drift database setup, migrations, and adapters
  │   ├── platform/             # Local notifications & platform service hooks
  │   └── routing/              # Navigation shells and app route tables
  │
  └── features/                 # Feature slices by product concern
      ├── <feature>/
      │   ├── domain/           # Feature models, logic, and local contracts
      │   ├── application/      # Action controllers (CreateX, GetX)
      │   └── presentation/     # UI widgets, screens, and view models
      │       ├── view_models/  # @riverpod state notifiers
      │       ├── providers/    # Reactive state and UI query providers
      │       └── widgets/      # Screen-level and leaf UI components
      └── <feature>/<feature>.dart  # Feature barrel file (the only allowed public entrypoint)

• core/domain/*: Reusable models and core repository contracts.
• core/persistence/repositories/*: Persistence implementations (Drift adapters).
• features/<feature>/domain/*: Pure domain models and rule checks specific to that feature concern.
• features/<feature>/application/*: Single-purpose workflow actions (e.g. CreateTask, SaveCheckIn).

​

Dependency Rules

• Feature code must only depend on another feature through its top-level public barrel file (e.g., import 'package:canthus/features/tasks/tasks.dart'). Deep imports into other feature folders are prohibited.
• Widgets do not import Drift database classes or query builders directly.
• Domain models are completely persistence-agnostic (no Drift schema or database row types).
• Data adapters in core/persistence/ map DB rows to-and-from domain models.

​

Operation Lifecycle (How It Works)

​

Read Flow

​

Command Flow

​

Compute Flow (Pacing & Mana Calculations)

• Database details stay in persistence adapters.
• The compute engine remains side-effect-free, replayable, and unit-test friendly.
• The action boundary orchestrates secondary side-effects (e.g., updating EWMA coefficient snapshots) in one place.

​

Application Actions: Purpose and Contract

• Represent exactly one system operation.
• Validate caller inputs.
• Call repository contracts or domain services.
• Map exceptions to typed failures using ApplicationFailureMapper.
• Emit structured logs via AppDiagnostics.
• Return ApplicationResult<T> (Success<T> or Failure<T>).

​

Repository Contracts vs Adapters

• Contracts live in lib/core/domain/repositories/ or lib/features/<feature>/domain/.
• Implementations (Adapters) live in lib/core/persistence/repositories/.

​

Composition Root (Provider Wiring)

• repository_providers.dart: Instantiates persistence adapters.
• logger_provider.dart & settings_providers.dart: Global diagnostic logs and SharedPreferences.
• Feature actions (e.g., task_actions_providers.dart, mana_actions_providers.dart): Centralizes action class instantiations.

​

Why It Works

1. Change Isolation: Code boundaries constrain modifications. SQL updates remain in core/persistence/, business calculations in domain/ or features/<feature>/domain/, and layouts in presentation/.
2. Testability: Tests map directly to structural boundaries:
   • test/data: Drift adapter and DB transaction behavior.
   • test/domain: Core domain models and orchestration.
   • test/features: Feature-specific domain and application logic.
   • test/ui: ViewModels and UI widget verification.
3. Determinism: Computation remains separated from database/UI, enabling replayable mana evaluations.

​

Rules for Adding New Code

​

Adding a Read Capability

1. Add/extend the contract in the relevant domain repository file.
2. Implement the read in the concrete Drift repository under core/persistence/repositories/.
3. Add a Get* or Watch* action in lib/features/<feature>/application/.
4. Register the action provider in lib/core/bootstrap/providers/.
5. Consume the provider in feature view models or UI screens.

​

Adding a Command/Write Capability

1. Extend the repository write API contract.
2. Implement transaction details in the concrete Drift adapter.
3. Add a mutation action in lib/features/<feature>/application/ wrapping inputs, logs, and results.
4. Expose ViewModel method invoking this action.
5. Trigger the ViewModel from the UI widget.

​

Adding a Domain Policy/Calculation

1. Add the policy or helper model in lib/features/<feature>/domain/ (or lib/features/mana/domain/engine/).
2. Write unit tests for the policy in test/features/ or test/domain/.
3. Wire the policy into application actions.

​

Common Pitfalls (And Correct Placement)

​

Related Docs

• Architecture
• Conventions & state management
• Feature flags
• Data schema
• The mana system