Clean Architecture in Flutter: A Practical Guide for Scalable Apps

The Core Objective: Inversion of Control and Isolation

The goal of Clean Architecture is not to maximize the number of folders in your project. It is to enforce a single fundamental rule: The Dependency Inversion Principle. High-level business rules must not depend on low-level implementation details; both must depend on abstractions.

In practical Flutter terms, your core business logic (e.g., calculating checkout totals, validating coupon codes, or managing user sessions) must never know or care whether your mobile app is using Firebase, a custom FastAPI backend, SQLite, or raw in-memory arrays. Your domain logic should be pure, framework-agnostic Dart that can run in a standalone CLI script without importing `package:flutter`.

The Pragmatic Three-Layer Architecture

For production mobile applications, I organize code into three distinct, decoupled layers:

• 1. Presentation Layer: Flutter Widgets, Screens, UI animations, theme styling, and State Management Notifiers/Blocs. This layer only communicates with the Domain layer.
• 2. Domain Layer: Pure Dart Entities, UseCases (optional for complex domain rules), and abstract Repository interfaces. This layer has zero external dependencies and zero Flutter imports.
• 3. Data Layer: Concrete Repository implementations, Remote DataSources (Dio, Http, GraphQL), Local DataSources (Isar, Hive, SecureStorage), and DTO/JSON Mappers.

// DOMAIN LAYER (Pure Dart - No Flutter)
class UserEntity {
  final String id;
  final String email;
  final bool isPremium;
  const UserEntity({required this.id, required this.email, required this.isPremium});
}

abstract class AuthRepository {
  Future<Either<Failure, UserEntity>> loginWithCredentials(String email, String password);
}

// DATA LAYER (Implementation Detail)
class AuthRepositoryImpl implements AuthRepository {
  final AuthRemoteDataSource remoteSource;
  final AuthLocalDataSource localSource;

  AuthRepositoryImpl({required this.remoteSource, required this.localSource});

  @override
  Future<Either<Failure, UserEntity>> loginWithCredentials(String email, String password) async {
    try {
      final userDto = await remoteSource.login(email, password);
      await localSource.saveAuthToken(userDto.token);
      return Right(userDto.toEntity());
    } on NetworkException catch (e) {
      return Left(ServerFailure(e.message));
    }
  }
}

Feature-First vs Layer-First Organization

A critical mistake is structuring your project by technical layers at the root: `/presentation`, `/domain`, `/data`. When an application scales past 30 screens, navigating between layers requires endless scrolling across distant folders.

Instead, structure your project 'Feature-First'. Each business capability gets its own dedicated folder containing its presentation, domain, and data layers. When a feature is completed, it is a self-contained module that can be edited, tested, or removed without impacting unrelated code.

lib/
├── core/                  # Shared utilities, theme tokens, network clients
│   ├── network/
│   ├── theme/
│   └── error/
├── features/
│   ├── auth/              # Feature module
│   │   ├── data/          # Models, Remote/Local DataSources, RepositoriesImpl
│   │   ├── domain/        # Entities, Repository Interfaces
│   │   └── presentation/  # Widgets, Screens, Controllers
│   ├── checkout/
│   └── profile/
└── main.dart

When to Omit UseCases (Avoiding Academic Overkill)

In dogmatic Clean Architecture, every interaction requires a UseCase class: `GetUserDetailsUseCase`, `UpdateCartUseCase`. But if all your UseCase does is call `return repository.getUserDetails();`, it is merely adding boilerplate indirection without providing value.

My pragmatic rule: Omit single-line pass-through UseCases. Allow your presentation state controllers (Blocs or Notifiers) to call Repository methods directly. Only introduce a dedicated UseCase when you need to coordinate multiple repositories or execute complex, multi-step business transactions.

Dependency Injection: Service Locator vs Provider Container

Clean Architecture relies heavily on the Dependency Inversion Principle: high-level presentation and domain modules must not depend on low-level network clients or SQLite database classes directly. Both must depend on abstractions.

In Flutter, there are two primary patterns to inject these dependencies: GetIt (a compile-agnostic Service Locator) and Riverpod ProviderContainer. Using GetIt, you register repository contracts as lazy singletons in a central injection container. In testing environments, you swap real API implementations with Mockito or Fake classes without altering a single widget.

// Core Dependency Injection Setup using GetIt
final sl = GetIt.instance;

void setupServiceLocator() {
  // External clients
  sl.registerLazySingleton<Dio>(() => Dio(BaseOptions(baseUrl: 'https://api.domain.com')));

  // Data sources & Repositories
  sl.registerLazySingleton<AuthRemoteDataSource>(() => AuthRemoteDataSourceImpl(sl()));
  sl.registerLazySingleton<AuthRepository>(() => AuthRepositoryImpl(sl()));

  // Presentation State
  sl.registerFactory(() => AuthBloc(sl()));
}