Flutter Feature Based Architecture

Flutter Feature-Based Architecture

Use this skill to keep Flutter code organized by product capability instead of broad technical layers. Prefer vertical feature slices under lib/features/, keep stable cross-feature code in lib/core/, use Riverpod as the state boundary between UI and data access, write models/providers by hand, and split UI into small StatelessWidget components.

First Pass

Before editing a project:

1. Inspect pubspec.yaml, lib/, route setup, serialization conventions, and existing Riverpod style.
2. Preserve coherent local conventions, especially folder names such as repository/ vs repositories/, components/ vs widgets/, and handwritten provider organization.
3. Prefer the smallest architecture change that solves the request.
4. State any dependency assumptions if Riverpod, routing, or serialization helpers are missing.
5. Run the project-standard checks after changes, usually flutter analyze and relevant tests.

Target Shape

Use this default shape for new projects or features unless the existing project already has a consistent equivalent:

lib/
├── app/                         # Optional app composition: shell, router, bootstrap
├── core/                        # Shared, cross-cutting concerns
│   ├── components/              # Reusable presentational widgets
│   ├── constants/               # App-wide constants and non-secret config
│   ├── extensions/              # Shared Dart extensions
│   ├── locales/                 # Localization setup and handwritten keys
│   ├── logger/                  # App-wide logging wrapper
│   ├── models/                  # Cross-feature models only
│   ├── providers/               # App-wide Riverpod providers
│   ├── repositories/            # Shared repositories and infrastructure services
│   ├── routes/                  # Route config if the app has no app/ layer
│   ├── theme/                   # ThemeData, text styles, component themes
│   └── utils/                   # General-purpose helpers
├── features/
│   └── orders/
│       ├── data/
│       │   ├── models/
│       │   └── repositories/
│       ├── providers/
│       └── views/
│           └── components/
└── main.dart

Core Layer

Move code to core/ only when it is genuinely app-wide or shared by multiple features. Keep feature-specific models, providers, repository methods, and UI components inside the owning feature until there is a stable reason to extract them.

Place composition code carefully:

• Let main.dart, app/, or core/routes/ import feature entry pages to wire navigation.
• Do not let one feature import another feature directly.
• Move shared contracts, route constants, data types, or UI primitives to core/ when two features need them.

Feature Layer

Use this internal structure for each feature:

features/<feature_name>/
├── data/
│   ├── models/                 # Feature-specific data/domain models
│   └── repositories/           # API, database, cache, and persistence access
├── providers/                  # Riverpod state, controllers, and query providers
└── views/
    ├── <feature>_page.dart     # Page/screen widgets
    └── components/             # Feature-only StatelessWidget components

Add optional folders only when they carry real weight:

Dependency Rules

• Import from core/ and the current feature only.
• Do not import from sibling features. Extract shared code to core/ instead.
• Keep views lean. Views handle layout, gestures, animation, navigation calls, and local-only UI concerns.
• Keep business rules, async work, persistence, and mutation orchestration in Riverpod notifiers/controllers or repositories.
• Keep repositories free of widget concerns. They should expose clear async APIs and translate data-source errors into app-level failures where the project has a failure type.
• Use setState only for strictly local ephemeral UI state. Do not use it for business data or cross-widget state.
• Do not split UI with private helper methods such as _buildHeader, _buildBody, _buildList, or _buildItem.
• Extract UI sections into named StatelessWidget classes under views/components/ instead.

Handwritten Dart Only

Do not introduce code generation for models, providers, routes, or serialization. Avoid freezed, json_serializable, riverpod_annotation, build_runner, generated part files, .g.dart, and .freezed.dart files unless the user explicitly asks for generated code.

When a project already contains generated files:

• Do not delete or rewrite existing generated architecture as part of an unrelated feature.
• Do not expand the generated surface for new work.
• Interact with existing generated APIs only when needed for compatibility.
• Ask before changing generator inputs if the task cannot be completed cleanly with handwritten Dart.

For handwritten models and state classes:

• Use immutable classes with final fields and const constructors where possible.
• Add factory Model.fromJson(Map<String, dynamic> json), Map<String, dynamic> toJson(), and copyWith().
• Add == and hashCode manually when value equality affects provider rebuilds, tests, collections, or state comparison.
• Keep parsing and serialization defensive enough for the app's data source.

Riverpod Defaults

Prefer the project's existing Riverpod style when it is internally consistent. For new handwritten Riverpod code, prefer current Riverpod primitives:

Use StateNotifierProvider only when the project already standardizes on StateNotifier or dependency constraints require it.

Provider Organization

In a feature's provider file, use this order:

1. Repository/service providers.
2. Simple filter or UI-state providers.
3. Query providers or notifier classes.
4. Provider declarations for controllers/notifiers.

Split a provider file when it becomes hard to scan, not just because a second provider exists. Prefer names that read naturally at call sites: orderRepositoryProvider, orderSearchQueryProvider, orderListProvider, orderControllerProvider.