Flutter Architecture

Structure every Flutter app as a layered, feature-first MVVM system, sized to the app. You must always answer "where does this code belong?" in one second. Based on Flutter's official Guide to app architecture, with Riverpod 3.x as the one mechanism for both state and dependency injection.

Two failure modes kill an architecture: under-structure (a widget touching a database) and over-structure (a

*UseCase

wrapping one repository call, an interface over code that already runs in a test). This skill fights both. Start small; add a layer only when it carries a load you can name.

Read the reference for the task at hand:

```
references/module-and-layers.md
```
— the layer model, folder-vs-package continuum, the DAG, barrels, feature-folder anatomy, and the "when multi-package (workspace)" note.
```
references/right-sizing.md
```
— the reject-over-engineering table, "abstract only what you can't test", and how architecture scales with app size.
```
references/state-di-riverpod.md
```
— provider graph, keepAlive vs autoDispose, placeholder-override composition root, isolate-safe factories,
```
ProviderContainer
```
tests.

Run

scripts/check_architecture.sh

before opening a PR.

Non-negotiable rules

Answer "where does this belong?" in one second. Group by feature first, layer second. No giant app-wide
```
screens/
```
,
```
models/
```
, or
```
widgets/
```
bucket — those smear one feature across the tree and force a name lookup on every edit.
Two layers minimum: UI and Data. A domain/use-case layer only when logic spans multiple repositories (projection, aggregation, a multi-step workflow). A
```
*UseCase
```
that forwards one repository call is a rename, not a boundary — Flutter's own guidance rates the domain layer conditional and says most apps don't need it.
Abstract exactly what cannot run in a test — name what the abstraction makes testable. A platform channel, network client, or plugin that can't execute in
```
flutter test
```
earns an interface + a fake. Code that already runs headless (an in-memory DB, a pure calculator, a repository over it) stays concrete. "It's cleaner" is not a load; if you can't name the seam it buys, don't add it.
Data flows one way; never skip or reverse a hop. Data down:
```
Service → Repository → ViewModel → View
```
. Events up:
```
View → ViewModel → Repository
```
. A widget calls its ViewModel only; a ViewModel calls repositories only. No two-way binding, no widget reaching a data source.
The View is dumb. A View does layout,
```
if
```
/
```
switch
```
on state, animation, and navigation — nothing else. No business logic, no formatting/number math, no
```
try/catch
```
, no data access. If a widget computes or fetches, it's in the wrong layer.
One ViewModel per feature, over immutable state. The ViewModel holds private mutable state and exposes intent methods (
```
load()
```
,
```
add(...)
```
); every transition assigns a new immutable value with value equality. No public setters, no mutable field the UI edits in place.
Repositories are the single source of truth AND the single write path. Every mutation is one named repository method that persists first, then publishes (one transaction where the store supports it). Never persist-after-publish — a crash in between credits state that never saved.
Derive, don't store. Counts, totals, streaks, filtered lists are computed from the source of truth (a stream/derived provider), never a second stored counter that can drift out of sync.
Map at the boundary; keep domain types out of the edges. Repositories map storage rows / JSON DTOs → immutable domain value objects. A generated Drift row or a
```
Map
```
never reaches a ViewModel or widget; unit math and locale formatting never happen in a widget.
Inject through providers; depend on the abstraction where it earns one. No globals, no singletons, no service locator reached from a widget, no
```
DateTime.now()
```
outside an injected
```
Clock
```
. A composition root wires the object graph once.
Features are FOLDERS; foundations become PACKAGES only when a compile wall is load-bearing. Default to a single package. A feature never imports another feature — share via a foundation layer or navigate by route ID. The dependency graph is a strict downward-only DAG.
Errors are typed values at boundaries. Repositories/use-cases return a sealed
```
Result
```
/
```
Failure
```
rather than throwing across a layer; the UI switches exhaustively. See
```
error-handling-typed-results
```
.

The layered shape (single package, the default)

project-structure-and-packages

OWNS the physical tree; this is the feature-first layout it defines, shown here for the layer semantics. Features are FOLDERS under

lib/features/

; a feature's Views and its one ViewModel live in

presentation/

text

lib/
  main.dart                 # thin entrypoint → bootstrap()
  bootstrap.dart            # composition root: build infra, override placeholder providers, runApp
  app.dart                  # MaterialApp.router, theme, top-level ProviderScope children
  core/                     # PURE foundation, NO Flutter: value objects, Result/Failure, the Clock seam,
                            #   extensions, pure calculators (the sanctioned foundation, not a junk-drawer)
  data/                     # shared data layer: Drift db, DAOs, repositories, row→model mappers
  services/                 # injectable side-effect ports + live impls (services/native/ = MethodChannel)
  routing/                  # the single go_router config, typed routes, guards
  theme/  l10n/             # ThemeExtension token sets; generated AppLocalizations + ARB
  features/
    tasks/
      presentation/
        task_list_screen.dart      # View: dumb ConsumerWidget
        task_list_notifier.dart    # ViewModel: StreamNotifier over immutable state
        widgets/                   # widget CLASSES used only by this feature
      application/                 # optional: use-cases, ONLY when logic spans repositories
      domain/                      # optional: feature-local models
      # data/ usually ABSENT — features read shared repos from lib/data/

Rules of thumb:

core/

depends on nothing above it and stays free of

BuildContext

;

data/

has no Flutter UI imports; a feature depends on

core

data

services

, never on a sibling feature. Add a feature-local

domain/

application/

(use-cases) folder only when logic spans repositories.

The feature slice (Riverpod-first "how")

A dumb View reads one ViewModel; the ViewModel holds private state and exposes intent methods.

dart

// features/tasks/presentation/task_list_notifier.dart — the ViewModel.
//   build() returns the live repository stream; a mutation commits through the single write
//   path and the watched stream RE-EMITS. No manual `state = ...` republish.
final class TaskListNotifier extends StreamNotifier<List<Task>> {
  @override
  Stream<List<Task>> build() {
    ref.onDispose(() {/* controllers/subscriptions released here */});
    return ref.watch(taskRepositoryProvider).watchTasks();   // track every emission
  }

  Future<void> add(String title) async {    // intent method — no setter
    final id = ref.read(idGeneratorProvider)();            // injected id source — never a UI UniqueKey
    await ref.read(taskRepositoryProvider).add(Task.create(id: id, title: title));
    // No republish: the committed write makes watchTasks() re-emit and build()'s stream updates state.
  }
}

final taskListNotifierProvider =
    StreamNotifierProvider<TaskListNotifier, List<Task>>(TaskListNotifier.new);

The repository behind it is the single source of truth AND single write path — a

watchTasks()

stream plus an

add()

that persists first, then the stream re-emits. Give it an

abstract interface

only when the real impl can't run in a test (rule 3); over an in-memory DB a concrete class is fine.

dart

// features/tasks/task_list_screen.dart — the View is dumb: read one provider, render.
final class TaskListScreen extends ConsumerWidget {
  const TaskListScreen({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final tasks = ref.watch(taskListNotifierProvider);
    return tasks.when(
      loading: () => const Center(child: CircularProgressIndicator()),
      error: (e, _) => ErrorView(onRetry: () => ref.invalidate(taskListNotifierProvider)),
      data: (list) => ListView(
        children: [for (final t in list) TaskTile(task: t)],   // widget CLASS, not a _buildTile()
      ),
    );
  }
}

Providers ARE the dependency injection. Wire deps via

ref.watch

, key per-entity state with

family

, and use

autoDispose

for per-screen controllers. See

state-management-riverpod

for the full API discipline (watch/read/listen split,

.select

, stale-closure hazards).

The composition root (single write of the object graph)

Infra that constructs asynchronously (a database, dirs, a key store) is injected via placeholder providers that throw until overridden in

bootstrap.dart

— the same seam tests use.

dart

// data/providers.dart — placeholder: throws until bootstrap() overrides it (and every test overrides it).
final appDatabaseProvider =
    Provider<AppDatabase>((ref) => throw UnimplementedError('override in bootstrap()'));

// bootstrap.dart — the ONE place async infra is built and the graph is composed.
Future<void> bootstrap() async {
  WidgetsFlutterBinding.ensureInitialized();
  final db = await openAppDatabase();       // plain top-level factory, no BuildContext
  runApp(ProviderScope(
    overrides: [appDatabaseProvider.overrideWithValue(db)],
    child: const App(),
  ));
}

Keep infra (DB, repositories, clock)

keepAlive

; never

autoDispose

a singleton that can be torn down mid-operation. See

app-startup-and-bootstrap

for main() ordering and error handlers.

Right-sizing: folder vs package, and what to abstract

Scale the architecture to the app. The three questions, in order:

Does this need a new folder or a new file? Almost always a file in an existing feature/layer.
Does this need a domain/use-case layer? Only if logic spans multiple repositories. One-repo CRUD does not.
Does this need an interface? Only if the real implementation can't run in
```
flutter test
```
, or you genuinely swap dev/prod impls. Name the fake it enables.
Does this need a separate package? Only when a compile-time wall is load-bearing — divergence would be a correctness bug (canonical units/money math, the whole data layer, a scheduler). See the reject-over-engineering table in
```
references/right-sizing.md
```
.

When multi-package (workspace). A large app (many teams, a pure-Dart core you golden-test, a reusable design system) may split foundations into packages under a Dart pub workspace. Then: each member sets
resolution: workspace
with one root
pubspec.lock
; each package exposes one barrel (
core.dart
) over a private
src/
— never import another package's
src/
; the pure-Dart
core
package declares no
flutter
dependency so a stray import is a compile error; the DAG stays acyclic (
core
→ nothing internal; everything →
core
; the app shell → all). This is an option a big app grows into, never a requirement for a small one — a single package with folders is the default.

Anti-patterns

A
*UseCase
/ domain layer wrapping one repository call. Pure ceremony; a rename of the repository method. Add the layer only when logic spans repositories.
An
abstract interface class
whose only content is the word "Repository", over code that runs in a test. The seam buys nothing; a Map-backed fake can even accept rows the real schema rejects. Test the concrete class against a real in-memory store.
Business logic, formatting, or number/unit math in a View. Move it to the ViewModel or
```
core
```
.
http
/
sqflite
/
SharedPreferences
/a plugin called inside
build()
or
initState()
. Data access belongs behind a repository, reached through a provider.
Persist-after-publish / optimistic write before the commit returns. A crash in the gap credits state that never saved. Persist first, then the stream republishes.
A stored counter mirroring derivable data (a
```
count
```
column next to the rows). It drifts. Derive it from the source of truth.
A ViewModel importing
package:flutter/material.dart
for
BuildContext
/widgets. ViewModels are UI-framework-light; passing
```
BuildContext
```
into the data layer is worse.
get_it
/
injectable
/
package:provider
as a second DI container alongside Riverpod, or a global singleton /
static
mutable store reached from a widget. Providers are the one DI mechanism.
A cross-feature import creating a cycle. Share via a foundation layer or navigate by route ID.
Splitting a small app into packages "to be clean". Multiplies pubspecs and codegen for zero compile-time guarantee. Promote to a package only for a load-bearing wall.

Definition of done

New code lives under the right
```
features/<x>/
```
or
```
core
```
/
```
data
```
location; grouping is feature-first.
The View is a dumb
```
ConsumerWidget
```
— no data access, no business logic, no formatting, no
```
try/catch
```
.
The ViewModel is a
```
Notifier
```
/
```
AsyncNotifier
```
/
```
StreamNotifier
```
exposing immutable state + intent methods; no public setters, no
```
notifyListeners()
```
in the Riverpod path.
Every mutation routes through one repository method that persists before publishing; the watched stream re-emits (no manual republish); derived reads are streams/derived providers, not stored counters.
Repositories map storage rows/DTOs → immutable value objects; no Drift/DTO/
```
Map
```
type reaches a ViewModel or widget.
Interfaces exist only where the real impl can't run in a test (or a real dev/prod swap); each earns a named fake.
Dependencies are injected via providers from a composition root; no new globals/singletons; no
```
DateTime.now()
```
outside an injected clock.
A domain/use-case layer was added only if logic spans repositories; the app is a single package unless a compile wall is load-bearing.

scripts/check_architecture.sh

passes;

dart analyze

is clean.

Related skills

See
```
state-management-riverpod
```
for the Notifier/AsyncNotifier API, watch/read/listen split,
```
family
```
+
```
autoDispose
```
, and stale-closure hazards.
See
```
widget-composition
```
for the deep dive on building the dumb View (rule 5): const widget classes over
```
_buildX()
```
helpers, lean
```
build()
```
, and where the widget sits in this layer DAG.
See
```
scaffold-feature-module
```
for the step-by-step feature folder + typed go_router registration workflow.
See
```
project-structure-and-packages
```
for pubspec-as-audit-artifact, barrels, and one-way layering mechanics.
See
```
app-startup-and-bootstrap
```
for main() ordering, global error handlers, and DI overrides at the root.
See
```
error-handling-typed-results
```
for the sealed
```
Result
```
/
```
Failure
```
spine returned across boundaries.
See
```
dart3-idioms-and-coding-standards
```
for sealed types, exhaustive switches, and immutable value types.

See

naming-conventions

for the

Screen

Notifier

Repository

Service

Failure

role suffixes a grep can read.

See
```
persistence-drift
```
for the DAO/repository seam and transaction-per-mutation persistence.

References

Provider / ChangeNotifier appendix

The same rules map onto the official Flutter-guide stack (

package:provider

ChangeNotifier

) when a codebase uses it instead of Riverpod. Rules 1–9, 11, 12 are unchanged. Only the "how" of state + DI differs:

ViewModel =
ChangeNotifier
. It still holds private mutable fields and exposes intent methods; after a real state change it calls
```
notifyListeners()
```
once — never inside
```
build()
```
and never in a tight loop. Expose state via getters that return unmodifiable views (
```
List.unmodifiable
```
). Immutability still applies to the domain models the ViewModel holds (
```
copyWith
```
, value equality).
DI = constructor injection wired through
provider
near the root. A
```
MultiProvider
```
at the app root creates services and repositories; a screen's
```
ChangeNotifierProvider
```
builds its ViewModel from
```
context.read<XRepository>()
```
. Depend on the abstract repository type so tests inject a fake.
Read vs listen:
```
context.watch<T>()
```
/
```
Consumer
```
to rebuild on change;
```
context.read<T>()
```
in callbacks. Never pass
```
BuildContext
```
down into the data layer to read providers — pass the data.
The bans still hold: no
```
get_it
```
/service locator reached from a widget, no global mutable state, no data access in a View. Everything else in this skill (layering, single write path, derive-don't-store, map-at-the-boundary, abstract-only-what-you-can't-test, folder-vs-package) is identical.

flutter-architecture

NPX Install

Tags

SKILL.md Content

Flutter Architecture

Non-negotiable rules

The layered shape (single package, the default)

The feature slice (Riverpod-first "how")

The composition root (single write of the object graph)

Right-sizing: folder vs package, and what to abstract

Anti-patterns

Definition of done

Related skills

References

Provider / ChangeNotifier appendix