Flutter Architecture

1---2name: flutter-architecture3description: Comprehensive guide for architecting Flutter applications following MVVM pattern and best practices with feature-first project organization. Use when working with Flutter projects to structure code properly, implement clean architecture layers (UI, Data, Domain), apply recommended design patterns, and organize projects using feature-first approach for scalable, maintainable apps.4metadata:5  author: Stanislav [MADTeacher] Chernyshev6  version: "1.0"7---8 9# Flutter Architecture10 11## Overview12 13Provides architectural guidance and best practices for building scalable Flutter applications using MVVM pattern, layered architecture, and recommended design patterns from the Flutter team.14 15## Project Structure: Feature-First vs Layer-First16 17Choose the right project organization based on your app's complexity and team size.18 19### Feature-First (Recommended for teams)20 21Organize code by business features:22 23```24lib/25├── features/26│   ├── auth/27│   │   ├── data/28│   │   ├── domain/29│   │   └── presentation/30│   ├── todos/31│   │   ├── data/32│   │   ├── domain/33│   │   └── presentation/34│   └── settings/35│       ├── data/36│       ├── domain/37│       └── presentation/38├── shared/39│   ├── core/40│   ├── data/41│   └── ui/42└── main.dart43```44 45**When to use:**46- Medium to large apps (10+ features)47- Team development (2+ developers)48- Frequently adding/removing features49- Complex business logic50 51**Benefits:**52- Features are self-contained units53- Easy to add/remove entire features54- Clear feature boundaries55- Reduced merge conflicts56- Teams work independently on features57 58See [Feature-First Guide](references/feature-first.md) for complete implementation details.59 60### Layer-First (Traditional)61 62Organize code by architectural layers:63 64```65lib/66├── data/67│   ├── repositories/68│   ├── services/69│   └── models/70├── domain/71│   ├── use-cases/72│   └── entities/73├── presentation/74│   ├── views/75│   └── viewmodels/76└── shared/77```78 79**When to use:**80- Small to medium apps81- Few features (<10)82- Solo developers or small teams83- Simple business logic84 85**Benefits:**86- Clear separation by layer87- Easy to find components by type88- Less nesting89 90## Quick Start91 92Start with these core concepts:93 941. **Separation of concerns** - Split app into UI and Data layers952. **MVVM pattern** - Use Views, ViewModels, Repositories, and Services963. **Single source of truth** - Repositories hold the authoritative data974. **Unidirectional data flow** - State flows from data → logic → UI98 99For detailed concepts, see [Concepts](references/concepts.md).100 101## Architecture Layers102 103Flutter apps should be structured in layers:104 105- **UI Layer**: Views (widgets) and ViewModels (UI logic)106- **Data Layer**: Repositories (SSOT) and Services (data sources)107- **Domain Layer** (optional): Use-cases for complex business logic108 109See [Layers Guide](references/layers.md) for detailed layer responsibilities and interactions.110 111## Core Components112 113### Views114- Compose widgets for UI presentation115- Contain minimal logic (animations, simple conditionals, routing)116- Receive data from ViewModels117- Pass events via ViewModel commands118 119### ViewModels120- Transform repository data into UI state121- Manage UI state and commands122- Handle business logic for UI interactions123- Expose state as streams or change notifiers124 125### Repositories126- Single source of truth for data types127- Aggregate data from services128- Handle caching, error handling, retry logic129- Expose data as domain models130 131### Services132- Wrap external data sources (APIs, databases, platform APIs)133- Stateless data access layer134- One service per data source135 136## Design Patterns137 138Common patterns for robust Flutter apps:139 140- **Command Pattern** - Encapsulate actions with Result handling141- **Result Type** - Type-safe error handling142- **Repository Pattern** - Abstraction over data sources143- **Offline-First** - Optimistic UI updates with sync144 145See [Design Patterns](references/design-patterns.md) for implementation details.146 147## When to Use This Skill148 149Use this skill when:150- Designing or refactoring Flutter app architecture151- Choosing between feature-first and layer-first project structure152- Implementing MVVM pattern in Flutter153- Creating scalable app structure for teams154- Adding new features to existing architecture155- Applying best practices and design patterns156 157## Resources158 159### references/160- [concepts.md](references/concepts.md) - Core architectural principles (separation of concerns, SSOT, UDF)161- [feature-first.md](references/feature-first.md) - Feature-first project organization and best practices162- [mvvm.md](references/mvvm.md) - MVVM pattern implementation in Flutter163- [layers.md](references/layers.md) - Detailed layer responsibilities and interactions164- [design-patterns.md](references/design-patterns.md) - Common patterns and implementations165 166### assets/167- [command.dart](assets/command.dart) - Command pattern template for encapsulating actions168- [result.dart](assets/result.dart) - Result type for safe error handling169- [examples/](assets/examples/) - Code examples showing architecture in practice