flutter-core:flutter-architecture

What this skill does

# Flutter Architecture

Master Flutter app architecture patterns including MVVM, Clean Architecture, and design patterns for building scalable, maintainable applications.

## When to Use This Skill

Use this skill when:

- Architecting a new Flutter application from scratch
- Refactoring an existing Flutter app to improve maintainability and scalability
- Implementing MVVM pattern with ViewModels and state management
- Applying Clean Architecture principles with proper layer separation
- Setting up dependency injection with get_it and injectable
- Organizing project structure (feature-based vs layer-based)
- Implementing repository and service patterns
- Building applications that require high testability
- Working on team projects with multiple developers
- Scaling a Flutter codebase for long-term maintenance

## Why Architecture Matters in Flutter

Architecture is the foundation of any successful Flutter application. While Flutter makes it easy to build beautiful UIs quickly, without proper architecture, applications become difficult to maintain, test, and scale as they grow.

### The Cost of Poor Architecture

Many Flutter developers start building apps without considering architecture, leading to:

- **Massive widget files** containing business logic, UI code, and data fetching all mixed together
- **Tight coupling** between components making changes risky and time-consuming
- **Difficult testing** because logic is embedded in widgets that require full widget testing
- **Merge conflicts** when multiple developers work on the same features
- **Slow onboarding** as new developers struggle to understand the codebase structure
- **Technical debt** that compounds over time, eventually requiring expensive rewrites

### The Benefits of Intentional Architecture

Investing in proper architecture from the start provides significant long-term benefits:

**Maintainability**: Well-architected code is easier to modify, update, and fix. When business requirements change (and they always do), you can make updates confidently without breaking unrelated features.

**Scalability**: Multiple developers can work on different features simultaneously without stepping on each other's toes. The clear separation of concerns means team members can focus on specific layers or features.

**Testability**: Separation of concerns makes it possible to write unit tests for business logic without dealing with widget trees or UI rendering. Simpler classes with well-defined inputs and outputs are easier to mock and test in isolation.

**Lower Cognitive Load**: New developers become productive faster when they can follow established patterns. Code reviews become easier when everyone follows the same architectural principles.

**Better User Experience**: Features ship faster with fewer bugs when the codebase is well-organized and testable. Developers can focus on delivering value rather than fighting with technical debt.

## MVVM Pattern in Flutter

Model-View-ViewModel (MVVM) is the recommended architectural pattern for Flutter applications. It separates a feature into three distinct parts that work together while maintaining clear boundaries.

### The Three Components

**Model**: Represents the data layer of your application. In Flutter MVVM, this includes repositories and services that fetch, cache, and manage data from various sources (APIs, databases, local storage). The Model layer is responsible for business rules related to data access and transformation.

**View**: Describes how to present application data to the user. Views are compositions of widgets that make up a feature or screen. In Flutter, a view is often a StatelessWidget or StatefulWidget that builds the UI based on state provided by the ViewModel.

**ViewModel**: Contains the logic that converts app data into UI state. The ViewModel sits between the Model and View, fetching data from repositories/services, processing it, and exposing it in a format that's ready for display. ViewModels also handle user interactions and trigger appropriate business logic.

### Key Principles of Flutter MVVM

**One-to-One Relationship**: Views and ViewModels should have a one-to-one relationship. Each screen or major feature should have its own ViewModel that manages state specifically for that view.

**Unidirectional Knowledge**: The View knows about the ViewModel, and the ViewModel knows about the Model, but the Model is unaware of the ViewModel, and the ViewModel is unaware of the View. This unidirectional dependency prevents circular dependencies and keeps concerns separated.

**State Management Integration**: ViewModels work with state management solutions like Provider, Riverpod, or BLoC to expose state to the View and notify it of changes. The choice of state management solution doesn't change the fundamental MVVM pattern.

### Why MVVM for Flutter

MVVM aligns naturally with Flutter's reactive programming model. The pattern works seamlessly with Flutter's state management ecosystem and provides clear guidelines for where different types of code should live. The official Flutter documentation, updated in 2026, recommends MVVM as the standard pattern for building scalable Flutter applications.

## Clean Architecture in Flutter

Clean Architecture takes the separation of concerns further by defining explicit layers with clear responsibilities and dependencies. While MVVM focuses on the UI layer, Clean Architecture provides a complete system architecture.

### The Three Layers

**Presentation Layer**: The outermost layer containing all UI components, widgets, screens, and presentation logic holders (ViewModels, Controllers, BLoCs). This layer depends on the Domain layer but is independent of data sources.

**Domain Layer**: The heart of the application containing core business logic, entities, and use cases. This layer is completely independent of frameworks, UI, and data sources. It's written in pure Dart without any Flutter dependencies.

**Data Layer**: Responsible for retrieving data from various sources (REST APIs, GraphQL, local databases, platform plugins). This layer implements the repository interfaces defined in the Domain layer.

### The Dependency Rule

The fundamental rule of Clean Architecture is the dependency rule: source code dependencies must point inward toward higher-level policies. The Domain layer doesn't depend on anything. The Data and Presentation layers both depend on the Domain layer but not on each other.

This is achieved through dependency inversion - the Domain layer defines abstract repository interfaces, and the Data layer provides concrete implementations. The Presentation layer depends on the Domain layer's use cases and entities, never directly on data sources.

### Communication Flow

State flows from the Data layer through the Domain layer and eventually to the Presentation layer. User events flow in the opposite direction: from the Presentation layer through use cases in the Domain layer and to repositories in the Data layer.

This unidirectional flow makes the system predictable and easy to reason about. Each layer has a clear responsibility and doesn't need to know about implementation details in other layers.

## SOLID Principles in Flutter

SOLID principles provide specific guidelines for writing clean, maintainable object-oriented code. Applying these principles in Flutter creates well-structured applications that are easier to understand, modify, and extend.

### Single Responsibility Principle (SRP)

A class should have only one reason to change. This prevents "god classes" that try to do everything. In Flutter, this means:

- Widgets focus only on UI layout and composition
- ViewModels handle only presentation logic for specific views
- Repositories focus only on data access for specific entities
- Services handle only specific business operations

### Open/Closed Principle (OCP)

Classes should be open for extension but closed for modification. Use inheritance, composition, and in