ulpi-io Flutter Architecture
Overview
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