Flutter Architecture
A structured methodology for defining the technical architecture of a Flutter app — covering structure, state management, routing, and the dependency stack — before any feature is implemented.
Guiding principle: Preserve existing architecture in active projects. Only recommend changes — do not apply them without explicit approval.
Workflow
- Gather context — read
docs/product/app_brief.md if it exists. Ask: app scale (small/medium/large), team size and Flutter experience, offline requirements, backend type (Firebase/Supabase/REST/none), release timeline, platform targets.
- Recommend architecture pattern — apply decision rules below.
- Design folder structure — feature-first or layer-first, based on app scale.
- Choose state management — apply decision rules in
@references/state-management-snippets.md.
- Define routing strategy — GoRouter for most apps; auto_route for heavy typed routing needs.
- Define dependency stack — list recommended packages with justifications. Query pub-dev MCP for current versions before pinning any.
- Document decisions — produce an ADR for each major choice. Use
templates/architecture_decision_record.md.
- Get user approval on the architecture plan before any implementation begins.
Architecture Pattern Decision Rules
| App profile |
Recommended pattern |
| Small app, 1-2 dev, simple state |
Layer-first, ChangeNotifier + ListenableBuilder |
| Medium app, team product |
Feature-first, Clean Architecture, Riverpod |
| Large app, multiple teams |
Feature-first, Clean Architecture, Riverpod or Bloc, Melos monorepo |
| Existing Bloc codebase |
Preserve Bloc; suggest Cubit where appropriate |
| Team has strong Bloc expertise |
Bloc/Cubit regardless of scale |
Default recommendation for new medium+ apps: feature-first structure with Riverpod, GoRouter, Freezed, Dio, flutter_secure_storage.
Feature-First Folder Structure
lib/
├── app/ # MaterialApp, router, theme, localization
├── core/ # config, constants, errors, network, utils, shared widgets
└── features/
└── <feature>/
├── data/ # DTOs, datasource interfaces+impls, repository impls
├── domain/ # entities, repository interfaces, use cases
└── presentation/ # controller/cubit, pages, widgets
See @references/feature-layer-template.md for per-layer file naming and patterns.
State Management Decision
See @references/state-management-snippets.md for full Riverpod and Bloc examples.
Quick rule:
- Riverpod — code gen, DI, compile-time safety, composable; best for new medium/large apps
- Bloc/Cubit — explicit event log, strong team expertise required; best for complex business flows
- ChangeNotifier — simple apps, minimal ceremony, no code gen
- GetX, Redux, MobX — avoid unless team has deep existing expertise
Routing Decision
| Router |
Use when |
go_router |
Most apps; supports deep links, web URLs, shell routes |
auto_route |
Strongly typed routes, complex guards, large navigation trees |
Navigator 2.0 directly |
Avoid — high boilerplate |
Recommended Default Stack (new medium+ app)
- State management: Riverpod + riverpod_annotation
- Routing: go_router
- HTTP: Dio + pretty_dio_logger (debug)
- Serialization: freezed + json_serializable
- Secure storage: flutter_secure_storage
- Local DB: Hive (simple) / Drift (relational) / Isar (high-perf)
- Linting: very_good_analysis or flutter_lints
- Testing: mocktail
Query pub-dev MCP (getPackage, getPackageScore) before pinning any package version.
Output Artifacts
docs/architecture/technical_plan.md — architecture overview (use templates/technical_plan.md)docs/architecture/architecture_decisions.md — ADR loglib/app/ — initial app, router, theme scaffoldlib/core/errors/ — Failure + AppException hierarchyanalysis_options.yaml — configured linting
Cross-references
- Agent:
flutter-architect
- State management patterns:
@references/state-management-snippets.md
- Layer patterns:
@references/feature-layer-template.md
- Error patterns:
@references/dart-error-mapping.md
- Package research: pub-dev MCP, context7 MCP
1---2name: flutter-architecture3description: Define, choose, or review the technical architecture for a Flutter app. Use when the user wants to structure a new Flutter project, choose a state management approach, set up routing, or review an existing architecture. Trigger phrases: "design Flutter architecture", "choose state management", "set up Flutter project structure", "what architecture should I use", "Flutter clean architecture", "feature-first Flutter", "help me structure my Flutter app", "should I use Riverpod or Bloc", "define the tech stack", "Flutter project setup". Also use when the product brief is complete and the user is ready to define the technical foundation.4---56# Flutter Architecture78A structured methodology for defining the technical architecture of a Flutter app — covering structure, state management, routing, and the dependency stack — before any feature is implemented.910**Guiding principle:** Preserve existing architecture in active projects. Only recommend changes — do not apply them without explicit approval.1112---1314## Workflow15161. **Gather context** — read `docs/product/app_brief.md` if it exists. Ask: app scale (small/medium/large), team size and Flutter experience, offline requirements, backend type (Firebase/Supabase/REST/none), release timeline, platform targets.172. **Recommend architecture pattern** — apply decision rules below.183. **Design folder structure** — feature-first or layer-first, based on app scale.194. **Choose state management** — apply decision rules in `@references/state-management-snippets.md`.205. **Define routing strategy** — GoRouter for most apps; auto_route for heavy typed routing needs.216. **Define dependency stack** — list recommended packages with justifications. Query pub-dev MCP for current versions before pinning any.227. **Document decisions** — produce an ADR for each major choice. Use `templates/architecture_decision_record.md`.238. **Get user approval** on the architecture plan before any implementation begins.2425---2627## Architecture Pattern Decision Rules2829| App profile | Recommended pattern |30|---|---|31| Small app, 1-2 dev, simple state | Layer-first, `ChangeNotifier` + `ListenableBuilder` |32| Medium app, team product | Feature-first, Clean Architecture, Riverpod |33| Large app, multiple teams | Feature-first, Clean Architecture, Riverpod or Bloc, Melos monorepo |34| Existing Bloc codebase | Preserve Bloc; suggest Cubit where appropriate |35| Team has strong Bloc expertise | Bloc/Cubit regardless of scale |3637**Default recommendation for new medium+ apps:** feature-first structure with Riverpod, GoRouter, Freezed, Dio, flutter_secure_storage.3839---4041## Feature-First Folder Structure4243```44lib/45├── app/ # MaterialApp, router, theme, localization46├── core/ # config, constants, errors, network, utils, shared widgets47└── features/48 └── <feature>/49 ├── data/ # DTOs, datasource interfaces+impls, repository impls50 ├── domain/ # entities, repository interfaces, use cases51 └── presentation/ # controller/cubit, pages, widgets52```5354See `@references/feature-layer-template.md` for per-layer file naming and patterns.5556---5758## State Management Decision5960See `@references/state-management-snippets.md` for full Riverpod and Bloc examples.6162Quick rule:63- **Riverpod** — code gen, DI, compile-time safety, composable; best for new medium/large apps64- **Bloc/Cubit** — explicit event log, strong team expertise required; best for complex business flows65- **ChangeNotifier** — simple apps, minimal ceremony, no code gen66- **GetX, Redux, MobX** — avoid unless team has deep existing expertise6768---6970## Routing Decision7172| Router | Use when |73|---|---|74| `go_router` | Most apps; supports deep links, web URLs, shell routes |75| `auto_route` | Strongly typed routes, complex guards, large navigation trees |76| `Navigator 2.0` directly | Avoid — high boilerplate |7778---7980## Recommended Default Stack (new medium+ app)8182- State management: Riverpod + riverpod_annotation83- Routing: go_router84- HTTP: Dio + pretty_dio_logger (debug)85- Serialization: freezed + json_serializable86- Secure storage: flutter_secure_storage87- Local DB: Hive (simple) / Drift (relational) / Isar (high-perf)88- Linting: very_good_analysis or flutter_lints89- Testing: mocktail9091Query pub-dev MCP (`getPackage`, `getPackageScore`) before pinning any package version.9293---9495## Output Artifacts9697- `docs/architecture/technical_plan.md` — architecture overview (use `templates/technical_plan.md`)98- `docs/architecture/architecture_decisions.md` — ADR log99- `lib/app/` — initial app, router, theme scaffold100- `lib/core/errors/` — Failure + AppException hierarchy101- `analysis_options.yaml` — configured linting102103---104105## Cross-references106107- Agent: `flutter-architect`108- State management patterns: `@references/state-management-snippets.md`109- Layer patterns: `@references/feature-layer-template.md`110- Error patterns: `@references/dart-error-mapping.md`111- Package research: pub-dev MCP, context7 MCP
yakoub-ai