Provides architectural guidance and best practices for building scalable Flutter applications using MVVM pattern, layered architecture, and recommended design patterns from the Flutter team.
Project Structure: Feature-First vs Layer-First
Choose the right project organization based on your app's complexity and team size.
Feature-First (Recommended for teams)
Organize code by business features:
lib/
├── features/
│ ├── auth/
│ │ ├── data/
│ │ ├── domain/
│ │ └── presentation/
│ ├── todos/
│ │ ├── data/
│ │ ├── domain/
│ │ └── presentation/
│ └── settings/
│ ├── data/
│ ├── domain/
│ └── presentation/
├── shared/
│ ├── core/
│ ├── data/
│ └── ui/
└── main.dart
When to use:
Medium to large apps (10+ features)
Team development (2+ developers)
Frequently adding/removing features
Complex business logic
Benefits:
Features are self-contained units
Easy to add/remove entire features
Clear feature boundaries
Reduced merge conflicts
Teams work independently on features
See
Feature-First Guide
for complete implementation details.
Layer-First (Traditional)
Organize code by architectural layers:
lib/
├── data/
│ ├── repositories/
│ ├── services/
│ └── models/
├── domain/
│ ├── use-cases/
│ └── entities/
├── presentation/
│ ├── views/
│ └── viewmodels/
└── shared/
When to use:
Small to medium apps
Few features (<10)
Solo developers or small teams
Simple business logic
Benefits:
Clear separation by layer
Easy to find components by type
Less nesting
Quick Start
Start with these core concepts:
Separation of concerns
- Split app into UI and Data layers
MVVM pattern
- Use Views, ViewModels, Repositories, and Services
Single source of truth
- Repositories hold the authoritative data
Unidirectional data flow
- State flows from data → logic → UI
For detailed concepts, see
Concepts
.
Architecture Layers
Flutter apps should be structured in layers:
UI Layer
Views (widgets) and ViewModels (UI logic)
Data Layer
Repositories (SSOT) and Services (data sources)
Domain Layer
(optional): Use-cases for complex business logic
See
Layers Guide
for detailed layer responsibilities and interactions.
Core Components
Views
Compose widgets for UI presentation
Contain minimal logic (animations, simple conditionals, routing)
Receive data from ViewModels
Pass events via ViewModel commands
ViewModels
Transform repository data into UI state
Manage UI state and commands
Handle business logic for UI interactions
Expose state as streams or change notifiers
Repositories
Single source of truth for data types
Aggregate data from services
Handle caching, error handling, retry logic
Expose data as domain models
Services
Wrap external data sources (APIs, databases, platform APIs)
Stateless data access layer
One service per data source
Design Patterns
Common patterns for robust Flutter apps:
Command Pattern
- Encapsulate actions with Result handling
Result Type
- Type-safe error handling
Repository Pattern
- Abstraction over data sources
Offline-First
- Optimistic UI updates with sync
See
Design Patterns
for implementation details.
When to Use This Skill
Use this skill when:
Designing or refactoring Flutter app architecture
Choosing between feature-first and layer-first project structure
Implementing MVVM pattern in Flutter
Creating scalable app structure for teams
Adding new features to existing architecture
Applying best practices and design patterns
Resources
references/
concepts.md
- Core architectural principles (separation of concerns, SSOT, UDF)
feature-first.md
- Feature-first project organization and best practices
mvvm.md
- MVVM pattern implementation in Flutter
layers.md
- Detailed layer responsibilities and interactions
design-patterns.md
- Common patterns and implementations
assets/
command.dart
- Command pattern template for encapsulating actions
result.dart
- Result type for safe error handling
examples/
- Code examples showing architecture in practice