Architecture
Generated apps use feature-first clean architecture. Shared contracts live in lib/core/. Each feature has its own domain, data and presentation layers.
Folder layout
text
lib/
app/ App widget (MaterialApp.router, or MaterialApp with Navigator; theme, l10n)
bootstrap.dart startup shared by every lib/main_<flavor>.dart
core/
config/ AppFlavor, AppConfig (base URL, DSNs via --dart-define)
di/ dependency injection (get_it modules or Riverpod providers)
error_reporting/ CrashReporter + adapter
logging/ AppLogger
network/ AppApiClient + implementation, AppFailure, converter, JsonSerializer, interceptors
asset_resolver/ ImageResourceResolver + SVG/PNG image resources
routing/ AppRoutes + the chosen router (go_router, auto_route or Navigator)
theming/ AppTheme, AppColors, AppSpacing, AppRadius, context extensions
widgets/ shared widgets (FailureView)
features/<name>/
domain/ entities, repository contracts, use cases (pure Dart)
data/ models (JSON), remote data sources, repository implementations
presentation/ screens + Cubits or Riverpod controllers
<name>.dart barrel: exports only the screenThe dependency rule
text
presentation -> domain <- datadomain/imports nothing fromdata/,presentation/or Flutter. It is plain Dart.data/implements the repository contracts fromdomain/.presentation/talks to use cases, never to data sources.- Features never import other features. Anything shared moves to
core/.
The rules
These are written into the app's AGENTS.md, so people and AI agents follow the same list.
- Network only through
AppApiClient. Never import Dio or viva_network_kit outsidelib/core/network/. - Errors are values. Data sources and repositories return
Either<AppFailure, T>. Nothing throws across layers. - State uses sealed classes, in a Cubit or a Riverpod controller.
- Navigation uses
context.push(AppRoutes.x)orcontext.go(...). NeverNavigator.pushor a raw path string. - Theme tokens only:
context.colors,context.appColors,context.textTheme,AppSpacing,AppRadius. NoColor(0x...), no bare padding numbers. - User-visible text comes from
context.l10n.<key>, with keys inlib/l10n/arb/app_en.arb. - Log through
AppLogger, and report unexpected errors throughCrashReporter. Noprint. - Secrets and base URLs never go in source. Use
--dart-defineor CI secrets. - Every change ships with tests, and
./scripts/quality_gate.shpasses before the change is done.
Theme tokens
dart
Padding(
padding: const EdgeInsets.all(AppSpacing.md), // 16
child: Text(
context.l10n.homeTitle,
style: context.textTheme.titleLarge,
),
)| Token | Values |
|---|---|
AppSpacing | xs 4, sm 8, md 16, lg 24, xl 32 |
AppRadius | sm 4, md 8, lg 16 |
AppColors | Brand colours as a ThemeExtension, with light and dark |