Mobile Flutter Core

Mobile Flutter Core

Shared model for the mobile-flutter cluster. The pattern, review, and architecture spokes all depend on these decisions — keep them consistent here so no spoke contradicts another.

1. The decision this cluster turns on: state management

Everything else (immutability, testing, rebuild discipline, DI) follows from which state solution you pick. Pick one per app and stay consistent. The two families:

• Immutable-state (BLoC/Cubit, Riverpod, Redux) — state is replaced, never mutated; new instances via copyWith/constructors; ==/hashCode over all fields. UI rebuilds when a new value is emitted.
• Reactive-mutation (MobX, GetX, Signals) — state is mutated through a tracked API (@action, .value, .obs); derived values use the computed mechanism; reactions/disposers must be cleaned up.

Default recommendation: Riverpod or BLoC for non-trivial apps (immutable, testable, explicit async states). Implementation patterns → dart-flutter-patterns; review rules per solution → flutter-dart-code-review (§4).

2. Immutable-state contract (the rule the decision implies)

• Model mutually-exclusive states as sealed types / union variants (or the solution's async type like Riverpod AsyncValue) — never boolean flags (isLoading + hasError is an impossible-state generator).
• Every async op models loading / success / error as distinct states; error states carry the error, loading states don't carry stale data.
• Collections inside state are exposed as unmodifiable views, not raw List/Map.
• Handle every variant exhaustively in the UI (Dart 3 switch expression enforces this).

3. Layered architecture (shared across Flutter & native/KMP)

Business logic lives outside the widget/UI layer, behind injected dependencies, with a repository abstracting data sources. Dependency direction points inward:

presentation ──> domain <── data
       │            ▲         │
       └── design ──┘         └── DB / network
domain depends on nothing framework-specific (pure Dart / pure Kotlin).

• Flutter UI structure (widget decomposition, clean layering) → dart-flutter-patterns.
• Native Android / Kotlin-Multiplatform modules, UseCases, Repositories, mappers, DI → android-clean-architecture.
• Rule: never expose DB entities/DTOs to the UI — map to domain models; keep domain import-pure.

4. Async & lifecycle safety (cross-cutting, non-negotiable)

• After any await in a StatefulWidget, check mounted (or context.mounted, Flutter 3.7+) before touching BuildContext — navigation, dialogs, ScaffoldMessenger.
• Cancel every manual subscription (.listen()), close stream controllers, cancel timers in dispose()/close(). Prefer declarative builders over manual subscriptions.
• Never store BuildContext in singletons, controllers, or static fields.
• Run futures concurrently (Future.wait / record .wait) instead of awaiting sequentially.

5. Version / tooling matrix

6. Shared guardrails

• One state-management solution and one routing approach per app; stay consistent.
• Business logic out of widgets; dependencies injected, never constructed in-place.
• Sealed/union states over boolean flags; exhaustive handling in UI.
• mounted-check BuildContext after every await; dispose every subscription.
• Keep domain framework-pure; map entities/DTOs → domain models at the boundary.
• Secrets via --dart-define/secure storage — never hardcoded in Dart, never logged.
• Run flutter analyze + the test suite in CI; failures block merges → flutter-dart-code-review.
• Flutter vs native/KMP: pick Flutter for a single cross-platform UI codebase; reach for android-clean-architecture (KMP) when you need shared business logic with fully native UI.