Flutter Architecture, Feature-First Skill

This skill defines how to design, structure, and implement Flutter applications using the recommended layered architecture with feature-first file organization.

It is state management agnostic: the business logic holder in the UI layer may be named ViewModel, Controller, Cubit, Bloc, Provider, or Notifier, depending on the chosen state management approach. The architectural rules apply equally to all of them.

When to Use

Use this skill when:

• Designing the folder/file structure of a new Flutter app or feature.
• Creating a new View, ViewModel, Repository, or Service.
• Deciding which layer owns a piece of logic.
• Wiring dependency injection between components.
• Adding a domain (logic) layer for complex business logic.
• Refactoring an existing app from type-first to feature-first organization.

---

1. Layers

Separate every app into a UI Layer and a Data Layer. Add a Logic (Domain) Layer between them only for complex apps.

┌──────────────────────────────────────────────────────────────┐
│   UI Layer    │  Views + business logic holders              │
│               │  (ViewModel / Cubit / Controller / Provider) │
├──────────────────────────────────────────────────────────────┤
│  Logic Layer  │  Use Cases / Interactors  (optional)         │
├──────────────────────────────────────────────────────────────┤
│   Data Layer  │  Repositories + Services                     │
└──────────────────────────────────────────────────────────────┘

Rules:

• Only adjacent layers may communicate. The UI layer must never access a Service directly.
• The Logic layer is added only when business logic is too complex for the business logic holder or is reused across multiple screens.
• Data changes always happen in the Data layer (SSOT = Repository). No mutation in UI or Logic layers.
• Follow unidirectional data flow: state flows down (Data → UI), events flow up (UI → Data).