Production guidance for Flutter native mobile applications. Based on the Flutter team's official architecture guide (2024), Riverpod documentation, Very Good Ventures patterns, and Andrea Bizzotto's architecture series.
For API contract design and HTTP semantics, see /api-design. For domain modeling, see /domain-design. For design system and accessibility, see /ux-design. For observability, see /observability.
1. Architecture — MVVM with Layered Data
Two mandatory layers, one optional. Based on the Flutter team's official architecture guide.
UI Layer Data Layer
View (Widget) Repository (single source of truth per data type)
ViewModel (Notifier/Cubit) Service (wraps external API/DB — no business logic)
Optional Domain Layer (use cases) only for large apps with shared cross-ViewModel logic.
Layer rules
- Views: stateless rendering only. No business logic, no async, no API calls, no
BuildContextleaking into ViewModels. - ViewModels: one per View. Transform data for display, hold UI state, expose commands. No widget references, no navigation calls, no platform APIs.
- Repositories: single source of truth per data type. Abstract data sources, handle caching, offline-first. Repositories never know about other repositories.
- Services: thin wrappers around APIs/databases. No business logic — that belongs in ViewModels or use cases.
Data flow (unidirectional)
User taps → View → ViewModel.command() → Repository → Service → API
↓
View rebuilds ← ViewModel notifies ← Repository emits new state
State flows down, events flow up. Never the reverse.
Generated API clients
When a project has an OpenAPI spec, generate the API client — never hand-write it:
- Use a Dart-native generator (e.g., Tonik, swagger_parser) that produces clean Dart code
- The generated client IS the Service layer — create Repositories that wrap it
- Generated code goes in a
packages/directory, treated as immutable - Wire into the project's
just genpipeline so it regenerates with the spec - Check the project's
CLAUDE.mdfor the specific generator and pipeline commands
Official design patterns
- Command pattern — wraps ViewModel methods, handles running/complete/error states
- Result — return type instead of throwing exceptions (explicit error handling)
- Repository pattern — offline-first, abstract data sources, caching
- Optimistic state — update UI immediately, rollback on failure
2. Project Structure — Feature-First
Organize around what the user does, not what the code is.
lib/
src/
common_widgets/ # Truly shared UI components
constants/ # App-wide constants
exceptions/ # Error types
features/
authentication/
presentation/ # Widgets + ViewModels
domain/ # Models
data/ # Repositories + Services + DTOs
budgets/
presentation/
domain/
data/
localization/
routing/
utils/
A feature is what the user does (authenticate, manage_budgets), not a screen name. Each feature owns its own layers.
3. State Management — Riverpod
Riverpod is the modern standard. Use flutter_riverpod + riverpod_generator.
Core rules
ref.watchinsidebuild()— reactive, triggers rebuildref.readoutsidebuild()— one-shot, for event handlers- Never cross these —
ref.readinbuild()causes stale data,ref.watchoutsidebuild()causes unnecessary rebuilds - All generated providers
autoDisposeby default — prevents memory leaks - Initialize state in
build(), not in Notifier constructors - No public properties on Notifiers — bypasses tracking
- No side effects in Notifier
build() - No
refusage after async gaps without checkingmounted - No unstable provider arguments (lists, functions, non-const objects)
Provider selection
Let riverpod_generator choose automatically via annotations:
@riverpod
class BudgetList extends _$BudgetList {
@override
Future<List<Budget>> build() async {
return ref.read(budgetRepositoryProvider).getAll();
}
}
When to use BLoC instead
Only if regulatory compliance demands event-driven audit trails (financial apps with strict logging requirements). The explicit Event → State pipeline is heavier but provides maximum traceability.
4. Navigation — go_router
Official Flutter team recommendation. Declarative, URL-based, supports deep linking.
final router = GoRouter(
routes: [
GoRoute(path: '/', builder: (_, __) => const HomeScreen()),
GoRoute(path: '/budgets/:id', builder: (_, state) => BudgetScreen(id: state.pathParameters['id']!)),
StatefulShellRoute.indexedStack(
builder: (_, __, child) => MainShell(child: child),
branches: [
StatefulShellBranch(routes: [/* dashboard routes */]),
StatefulShellBranch(routes: [/* assets routes */]),
StatefulShellBranch(routes: [/* settings routes */]),
],
),
],
redirect: (context, state) {
final isLoggedIn = /* check auth state */;
if (!isLoggedIn) return '/login';
return null;
},
);
Key patterns
- Auth guards:
redirectparameter (must be synchronous — async auth checks need workarounds) - Bottom nav:
StatefulShellRoutewith independent navigator stacks per tab - Deep linking: define URL patterns, go_router handles
myapp://budgets/123automatically - Type-safe params: use
state.pathParameters['id']with null checks
5. Models — Freezed
Immutable domain models with code generation. Required for Riverpod state correctness.
@freezed
class Budget with _$Budget {
const factory Budget({
required String id,
required String name,
required String limitAmount, // BigDecimal as string — never double
required String currency,
required BudgetPeriod period,
}) = _Budget;
factory Budget.fromJson(Map<String, dynamic> json) => _$BudgetFromJson(json);
}
Generates: copyWith, ==, hashCode, toString, JSON serialization, union types.
Generated vs hand-written models
If the project generates models from an OpenAPI spec, use those directly. Only create hand-written Freezed models for:
- Local-only domain objects (not in the API)
- Drift database companions (mapping generated API models to local storage)
- View-specific state objects
Rules
- Run
dart run build_runner buildafter model changes (or the project's equivalentjustrecipe) - Never hand-edit
*.g.dartor*.freezed.dartfiles - Monetary values as
String— neverdouble. Match the backend's BigDecimal/Numeric contract. - All domain models get Freezed. DTOs for API responses get
json_serializableonly (lighter).
6. Widget Composition
Build method discipline
- Keep
build()cheap — it is called frequently (every frame during animations) constconstructors aggressively — 30-40% rebuild reduction- Prefer
StatelessWidgetover helper methods for reusable UI - Localize
setState()to the smallest subtree possible - Split widgets by change pattern, not just size — if two parts of a widget rebuild at different rates, extract the fast one
Anti-patterns
Opacitywidget in animations → useAnimatedOpacityorFadeInImage- Building large concrete child lists → use builder callbacks (
ListView.builder) saveLayer()is extremely expensive → avoidShaderMask,ColorFilterin animations- Helper functions instead of widgets → lose framework optimizations (key diffing, const, rebuild isolation)
- Overriding
operator==on Widgets → causes O(N^2) framework behavior
Performance tools
RepaintBoundaryfor frequently-updating components (20-30% paint time reduction)ListView.builder/GridView.builderfor lazy loading (70-80% memory reduction for 100+ items)Isolate.run()orcompute()for CPU-bound tasks (JSON parsing, heavy math)- Frame budget: 16ms at 60Hz, 8ms at 120Hz
- Always profile in release mode —
flutter run --release. Debug mode is 10x slower.
7. Theming — Material 3
M3 is the default since Flutter 3.16.
Seed-based color system
ThemeData(
useMaterial3: true,
colorScheme: ColorScheme.fromSeed(
seedColor: Colors.blue,
brightness: Brightness.light,
),
)
- Same seed color for light and dark themes — Flutter generates harmonized palettes
- Never override individual
ColorSchemecolors unless you have a specific reason — breaks seed algorithm harmony - Access colors via
Theme.of(context).colorScheme.primary, never hardcode hex values
Three-level override hierarchy
- ColorScheme (seed) — recommended, generates everything
- Component theme —
elevatedButtonTheme,cardThemefor category-wide overrides - Widget-level —
ElevatedButton.styleFrom(...)for one-offs
Custom design tokens via ThemeExtension
For tokens that don't exist in Material 3 (spacing, brand colors):
@immutable
class AppSpacing extends ThemeExtension<AppSpacing> {
final double small;
final double medium;
final double large;
const AppSpacing({this.small = 8, this.medium = 16, this.large = 24});
@override
AppSpacing copyWith({double? small, double? medium, double? large}) =>
AppSpacing(small: small ?? this.small, medium: medium ?? this.medium, large: large ?? this.large);
@override
AppSpacing lerp(AppSpacing? other, double t) => /* interpolation for animations */;
}
Register on ThemeData(extensions: [AppSpacing()]), consume via Theme.of(context).extension<AppSpacing>()!.
Dark mode
MaterialApp(
theme: lightTheme,
darkTheme: darkTheme,
themeMode: ThemeMode.system, // auto-switch with OS
)
8. Testing
Trophy-shaped test distribution
| Layer | Tool | Proportion | Purpose |
|---|---|---|---|
| Widget tests | flutter_test |
~50% | UI components, user interaction |
| Unit tests | test |
~30% | ViewModels, repositories, services |
| Golden tests | alchemist |
~10% | Visual regression for stable components |
| E2E | patrol |
~10% | Critical user journeys, native interactions |
Principles
- Fakes over mocks (official recommendation) — write fake repositories with deterministic behavior
- Push tests down — if a widget test gives the same confidence as E2E, write the widget test
- No duplication across layers — higher-level failure without lower-level failure signals a missing lower test
- Test the behavior, not the implementation — pump, tap, verify text/widget presence
Mocking
- Mocktail (no codegen, null-safe) — recommended for most projects
- Mockito (codegen, strict typing) — for large codebases with verification needs
- Create abstract repository interfaces to facilitate testing with fakes
Widget test pattern
testWidgets('displays budget amount', (tester) async {
await tester.pumpWidget(
ProviderScope(
overrides: [budgetProvider.overrideWith(() => FakeBudgetNotifier())],
child: const MaterialApp(home: BudgetScreen()),
),
);
expect(find.text('500.00 EUR'), findsOneWidget);
});
Golden tests with Alchemist
For visual regression on stable, reusable components. Gate PRs on pass/fail. Run headless in CI.
E2E with Patrol
Patrol handles native interactions that integration_test cannot: system dialogs, permissions, biometrics, cross-app testing.
9. Platform Channels
For native iOS/Android code integration (biometrics, push notifications, file system):
const platform = MethodChannel('com.example.app/native');
Future<String?> getBiometricType() async {
try {
return await platform.invokeMethod<String>('getBiometricType');
} on PlatformException catch (e) {
debugPrint('Platform channel error: ${e.message}');
return null;
}
}
- Always handle
PlatformException— the native side may not implement the method - Use
EventChannelfor streams (sensor data, location updates) - Prefer existing plugins (
local_auth,firebase_messaging) over custom channels
10. Code Generation Workflow
Flutter relies heavily on code generation. The build sequence matters.
# After model/provider changes
dart run build_runner build --delete-conflicting-outputs
# Watch mode during development
dart run build_runner watch --delete-conflicting-outputs
Generated files (never hand-edit)
*.freezed.dart— Freezed model implementations*.g.dart— JSON serialization + Riverpod providers*.gen.dart— other generators (theme_tailor, etc.)
Add to .gitignore or commit them — project choice, but be consistent. Committing avoids build_runner in CI; gitignoring keeps diffs clean.
11. Key Packages
| Category | Package | Notes |
|---|---|---|
| State | flutter_riverpod + riverpod_generator |
Modern standard |
| Navigation | go_router |
Official recommendation |
| Models | freezed + json_serializable |
Immutable + JSON |
| Codegen runner | build_runner |
Required for freezed/riverpod |
| HTTP | dio |
Interceptors, retry, logging |
| Local storage | drift (SQL) or shared_preferences (KV) |
Per use case |
| Linting | flutter_lints + custom_lint |
Both recommended |
| Testing (mock) | mocktail |
No codegen, null-safe |
| Testing (E2E) | patrol |
Native interactions |
| Testing (golden) | alchemist |
Visual regression |
| Theming codegen | theme_tailor |
ThemeExtension boilerplate |
12. Anti-patterns Summary
| Anti-pattern | Why it fails | Fix |
|---|---|---|
ref.read in build() |
Stale data, misses updates | Use ref.watch |
ref.watch outside build() |
Unnecessary rebuilds | Use ref.read |
| Business logic in Views | Untestable, violates MVVM | Move to ViewModel |
double for money |
Precision loss | String end-to-end (BigDecimal on server) |
| Helper functions for reusable UI | Loses framework optimizations | Extract to StatelessWidget |
| Profiling in debug mode | 10x slower, misleading results | flutter run --release |
Opacity in animations |
Expensive saveLayer call |
AnimatedOpacity |
| Repositories knowing each other | Circular deps, testing nightmare | Combine in ViewModel or use case |
| Logic in Notifier constructor | Runs before provider is tracked | Initialize in build() |
GetX |
Maintenance-mode, magic globals | Riverpod or BLoC |
13. Shared Resources
Translations
When web and mobile share the same API, share translations too:
- Web locale files (JSON/i18next) are the source of truth
- Generate mobile ARB files from web JSON via a conversion script
- Wire into the project's build pipeline so translations stay in sync
- Never duplicate translation keys manually across platforms
API Clients
When an OpenAPI spec exists:
- Generate clients for ALL platforms from the same spec
- The derivation chain flows: API code → OpenAPI spec → generated clients
- Check the project's
generated-coderule for the specific pipeline