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

1. 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.
2. Recommend architecture pattern — apply decision rules below.
3. Design folder structure — feature-first or layer-first, based on app scale.
4. Choose state management — apply decision rules in @references/state-management-snippets.md.
5. Define routing strategy — GoRouter for most apps; auto_route for heavy typed routing needs.
6. Define dependency stack — list recommended packages with justifications. Query pub-dev MCP for current versions before pinning any.
7. Document decisions — produce an ADR for each major choice. Use templates/architecture_decision_record.md.
8. Get user approval on the architecture plan before any implementation begins.