flutter-app-architecture

Flutter App Architecture Skill

This skill defines how to structure Flutter applications using layered architecture, proper data flow, and MVVM patterns for maintainability and testability.

When to Use

Use this skill when:

• Scaffolding a new Flutter project with layered architecture.
• Creating or refactoring View Models, Repositories, or Services.
• Wiring dependency injection between architectural components.
• Implementing unidirectional data flow across layers.
• Adding a Domain (Logic) Layer for complex business logic or shared use cases.

---

1. Layer Structure

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

┌──────────────────────────────────────────────────────────────┐
│   UI Layer    │  Views + ViewModels                           │
├──────────────────────────────────────────────────────────────┤
│  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.
• 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).

---

2. Component Responsibilities

View

• Describes how to present data; keep logic minimal and UI-related only.
• Passes events to the ViewModel in response to user interactions.

ViewModel

• Converts app data into UI state and maintains the current state needed by the View.
• Exposes callbacks (commands) to the View and retrieves/transforms data from Repositories.

class BookingViewModel extends ChangeNotifier {
  final BookingRepository _repo;

  BookingViewModel(this._repo);

  List<Booking> _bookings = [];
  List<Booking> get bookings => List.unmodifiable(_bookings);

  bool _isLoading = false;
  bool get isLoading => _isLoading;

  Future<void> loadBookings() async {
    _isLoading = true;
    notifyListeners();

    _bookings = await _repo.getBookings();
    _isLoading = false;
    notifyListeners();
  }

  Future<void> cancelBooking(String id) async {
    await _repo.cancelBooking(id);
    _bookings = await _repo.getBookings();
    notifyListeners();
  }
}