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:

1. •Separation of concerns - Split app into UI and Data layers
2. •MVVM pattern - Use Views, ViewModels, Repositories, and Services
3. •Single source of truth - Repositories hold the authoritative data
4. •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