flutter-app-architecture

name	flutter-app-architecture
description	Use when scaffolding a project, refactoring into layers, creating view models/repositories, configuring dependency injection, or implementing unidirectional data flow (MVVM).

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();
  }
}

Repository (Single Source of Truth)

• The only class that may mutate its data; all other classes read from it.
• Handles caching, error handling, and data refresh logic.
• Transforms raw data from Services into domain models.

class BookingRepository {
  final BookingApiService _apiService;
  final BookingLocalService _localService;

  BookingRepository(this._apiService, this._localService);

  Future<List<Booking>> getBookings() async {
    try {
      final remote = await _apiService.fetchBookings();
      await _localService.cacheBookings(remote);
      return remote;
    } catch (_) {
      return _localService.getCachedBookings();
    }
  }

  Future<void> cancelBooking(String id) async {
    await _apiService.cancelBooking(id);
    await _localService.removeCachedBooking(id);
  }
}

Service

• Wraps API endpoints and exposes asynchronous response objects.
• Isolates data-loading and holds no state.

class BookingApiService {
  final http.Client _client;
  BookingApiService(this._client);

  Future<List<Booking>> fetchBookings() async {
    final response = await _client.get(Uri.parse('/api/bookings'));
    if (response.statusCode != 200) {
      throw HttpException('Failed to load bookings');
    }
    final data = jsonDecode(response.body) as List;
    return data.map((json) => Booking.fromJson(json)).toList();
  }
}

---

3. Dependency Injection

Supply dependencies via constructors. Define abstract interfaces so implementations can be swapped for testing.

// Abstract interface for the repository
abstract class BookingRepository {
  Future<List<Booking>> getBookings();
  Future<void> cancelBooking(String id);
}

// Concrete implementation
class BookingRepositoryImpl implements BookingRepository {
  final BookingApiService _api;
  BookingRepositoryImpl(this._api);

  @override
  Future<List<Booking>> getBookings() => _api.fetchBookings();

  @override
  Future<void> cancelBooking(String id) => _api.cancelBooking(id);
}

---

4. Use Cases (Domain Layer)

Introduce use cases only when:

• Logic is complex or does not fit cleanly in the UI or Data layers.
• Logic is reused across multiple ViewModels or merges data from multiple Repositories.

class GetUpcomingBookingsUseCase {
  final BookingRepository _bookingRepo;
  final UserRepository _userRepo;

  GetUpcomingBookingsUseCase(this._bookingRepo, this._userRepo);

  Future<List<Booking>> call() async {
    final user = await _userRepo.getCurrentUser();
    final bookings = await _bookingRepo.getBookings();
    return bookings
        .where((b) => b.userId == user.id && b.date.isAfter(DateTime.now()))
        .toList();
  }
}

---

5. Workflow: Scaffold a New Feature

1. Create the Service — implement the API wrapper with typed response parsing.
2. Create the Repository — inject the Service, implement caching and error-handling logic.
3. Create the ViewModel — inject the Repository, expose UI state and commands.
4. Create the View — bind to the ViewModel, render state, dispatch events.
5. Wire DI — register all components in the dependency injection container.
6. Verify — confirm the View never accesses the Service directly and data flows unidirectionally.

---

6. Data Storage

• Use key-value storage (e.g., shared_preferences) for configuration and preferences.
• Use SQL storage (e.g., drift, sqflite) for complex relational data.
• Implement optimistic updates to improve perceived responsiveness by updating UI before server confirms.
• Support offline-first by combining local and remote data sources in Repositories.

---

7. Coding Conventions

• Use StatelessWidget when possible; avoid unnecessary StatefulWidgets.
• Keep build methods simple and focused on rendering.
• Prefer final for fields and top-level variables. Prefer const constructors when the class supports it.
• Prefer explicit typing on public APIs (e.g., Command0<void> over dynamic signatures).
• Use descriptive constant names (e.g., _todoTableName over _kTableTodo).

---

References

• Flutter app architecture guide
• Flutter Website GitHub Repository