mobile-flutter-core

name	mobile-flutter-core
description	Shared reference for the mobile-flutter cluster: the state-management decision (which solution, and the immutable-state contract it implies), the layered-architecture rule, the async/lifecycle safety rules, and the Dart/Flutter/KMP version & tooling matrix. USE WHEN choosing a state solution, designing the data/domain boundary, or aligning Flutter/Android/KMP tooling — the decisions every spoke shares.
cluster	mobile-flutter
version	1.0.0

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.

Concern	BLoC/Cubit	Riverpod	Provider	GetX	MobX	Signals
Container	Bloc/Cubit	Notifier/AsyncNotifier	ChangeNotifier	GetxController	Store	signal()
UI consumer	BlocBuilder	ConsumerWidget	Consumer	Obx/GetBuilder	Observer	Watch
Selector	buildWhen/BlocSelector	ref.watch(p.select)	Selector	—	computed	computed()
Disposal	auto via BlocProvider	.autoDispose	auto via Provider	onClose()	ReactionDisposer	manual
Testing	blocTest()	ProviderContainer	directly	Get.put	store directly	signal directly

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

Layer	Target	Notes
Language	Dart 3+	sealed classes, records, patterns, exhaustive switch are assumed
Flutter	3.7+	context.mounted guard; current widget/perf APIs
Codegen	freezed + *.g.dart	generated files current or git-ignored
Routing	GoRouter (declarative)	one routing approach per app — no mixing imperative + declarative
Networking	Dio (interceptors, one-time refresh-retry guard)	secure storage for tokens
Native / KMP	Kotlin + Room (Android) / SQLDelight + Ktor (KMP)	DI via Koin (KMP) or Hilt (Android)
Lint	strict analysis_options.yaml	strict-casts/inference/raw-types; very_good_analysis or flutter_lints

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.