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