Flutter Clean Architecture for Maintainable Mobile Apps

A Flutter application often begins with deceptive simplicity. With a handful of widgets, a state notifier, and direct HTTP calls via http or dio, a team can assemble a functional prototype in days. However, as the application expands into a production mobile product, this informal structure rapidly deteriorates under real-world requirements.

Features accumulate authentication tokens, multi-step validation rules, local caching, offline synchronization queues, analytics events, transient network failures, and intricate UI states. When these responsibilities share the same classes:

• widgets begin issuing direct network requests and decoding raw JSON payloads;
• state controllers manipulate database cursors and execute business calculations;
• backend schema changes force breaking refactors across dozens of UI layout files;
• writing unit tests requires mocking the entire Flutter widget tree, HTTP clients, and database engines simultaneously.

Clean Architecture addresses this coupling. It is not an exercise in creating nested folder hierarchies or manufacturing boilerplate interfaces for every single class. Instead, it is an architectural discipline designed to enforce the Dependency Inversion Principle: keeping core business policies completely independent of UI frameworks, database engines, network clients, and third-party software development kits (SDKs).

This guide provides a comprehensive, production-tested implementation of Clean Architecture in Flutter using modern Dart 3 idioms. We will examine the core dependency rules, establish strict boundaries between Domain Entities and Data Transfer Objects (DTOs), implement functional error handling with sealed class hierarchies, build a complete end-to-end vertical slice, and analyze critical architectural anti-patterns.

---

1. The Core Dependency Rule and Layer Boundaries

Clean Architecture—derived from Uncle Bob's original formulation and adapted for modern reactive client frameworks—organizes an application into concentric layers. The governing constraint is The Dependency Rule:

Source code dependencies must point strictly inward toward higher-level policies. Inner layers must have zero knowledge of outer layers, their classes, their functions, or their data structures.

In a Flutter application, this architecture organizes into three distinct layers:

┌─────────────────────────────────────────────────────────────┐
│                    PRESENTATION LAYER                       │
│   Widgets • State Notifiers • ViewModels • UI State Machines │
└──────────────────────────────┬──────────────────────────────┘
                               │ (depends on)
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                       DOMAIN LAYER                          │
│   Entities • Value Objects • Use Cases • Repository Ports   │
│                 (Pure Dart — Zero Flutter)                  │
└──────────────────────────────▲──────────────────────────────┘
                               │ (implements contracts)
┌──────────────────────────────┴──────────────────────────────┐
│                        DATA LAYER                           │
│  Repository Implementations • Remote/Local DataSources • DTOs│
└─────────────────────────────────────────────────────────────┘

Notice the dependency inversion occurring at the Data layer boundary. The Domain layer defines the abstract contract (a repository port), while the Data layer implements that contract (an adapter). High-level business logic never depends on concrete database drivers or network libraries; instead, both the Presentation and Data layers converge upon the stable abstractions defined within the Domain.

Clean Architecture Layer Matrix

| Layer | Primary Responsibilities | Permitted Dependencies | Prohibited Dependencies | Core Artifacts | | :--- | :--- | :--- | :--- | :--- | | Domain | Expresses enterprise and application business logic, models core entities, defines repository contracts. | Pure Dart standard library (dart:core, dart:async, dart:math). | package:flutter/*, dart:io, dart:ui, external HTTP or database packages. | Entities, Value Objects, Use Cases (Interactors), Repository Interfaces. | | Data | Fetches, persists, serializes, and deserializes raw payloads; implements repository contracts; translates exceptions into domain failures. | Domain layer, I/O libraries (dart:io), serialization packages, database engines (sqflite, hive), HTTP clients. | Presentation layer (package:flutter/widgets.dart), UI controllers. | Data Transfer Objects (DTOs), Remote Data Sources, Local Data Sources, Repository Implementations. | | Presentation | Renders UI widgets, captures user gestures, binds to state notifiers, manages visual layout and animations. | Domain layer, Flutter framework (package:flutter/*), state management tooling (Riverpod, Bloc, Provider). | Concrete Data layer classes (e.g., UserRepositoryImpl, ApiClient), raw SQL/JSON payloads. | Pages, Screen Widgets, Presentation Controllers, ViewModels, Sealed UI States. |

Why the Domain Layer Must Remain Pure Dart

The Domain layer is the conceptual core of your business. If your team decides to migrate from Flutter to another Dart client environment (such as server-side Dart, Dart CLI tools, or web-based background workers), the Domain layer should compile and execute without modifying a single line of code.

More importantly, keeping the Domain layer free of package:flutter/* dependencies yields three immediate engineering advantages:

1. Lightning-Fast Unit Tests: Domain unit tests run directly on the standard Dart Virtual Machine without initializing Flutter test bindings, layout engines, or asset bundles. Hundreds of domain logic tests can execute in milliseconds.
2. Zero Framework Churn: Changes to Flutter's rendering APIs, widget life-cycles, or third-party state packages cannot cascade into your business logic.
3. Purity of Thought: Engineers working on business workflows are constrained from taking shortcuts, such as accessing BuildContext or dispatching navigation events directly from business rules.

---

2. Entities vs. Data Transfer Objects (DTOs)

One of the most widespread structural flaws in Flutter codebases is passing API response models directly into presentation widgets:

❌ ANTI-PATTERN: Leaking API Schemas into the UI Tree
[ Backend JSON ] ──> [ UserDto ] ──> [ ProfileScreen Widget ]

When a backend service updates a key (for example, renaming user_name to display_name or restructuring a nested user profile payload), every widget displaying that user field breaks. Furthermore, API schemas often include serialization metadata, wire-format quirks (e.g., string representations of integers, Unix timestamps in milliseconds, or nullability indicators), and transport-specific flags that have no relevance to application business logic.

Clean Architecture solves this by strictly separating Domain Entities from Data Transfer Objects (DTOs).

✅ CLEAN ARCHITECTURE BOUNDARY: Explicit Mapping Isolation
[ Backend JSON ] ──> [ UserDto ] ──( .toDomain() )──> [ User Entity ] ──> [ Presentation Widget ]
                                  ▲
                         Data Layer Boundary

The Roles Defined

• Domain Entity: A business model defined purely by its domain identity and invariants. It uses rich Dart types (such as DateTime, enums, records, or custom Value Objects) and encapsulates business behavior. It contains zero knowledge of JSON keys, database column names, or network protocols.
• Data Transfer Object (DTO): An infrastructure model whose sole purpose is mirroring the wire format of an external service or database table. It handles serialization (fromJson, toJson), field nullability fallback, and format validation. It provides an explicit mapper method (e.g., .toDomain()) to translate external payloads into domain entities.

Isolating External Schema Volatility

Consider an API endpoint returning user profile data. The wire format contains snake_case keys, a Unix timestamp, and a verification date string:

// DATA LAYER: lib/features/profile/data/models/user_profile_dto.dart
import '../../domain/entities/user_profile.dart';

class UserProfileDto {
  const UserProfileDto({
    required this.userId,
    required this.userName,
    required this.emailAddress,
    required this.emailVerifiedAt,
    required this.registeredTimestampMs,
  });

  final String userId;
  final String userName;
  final String emailAddress;
  final String? emailVerifiedAt;
  final int registeredTimestampMs;

  factory UserProfileDto.fromJson(Map<String, dynamic> json) {
    return UserProfileDto(
      userId: json['user_id'] as String,
      userName: json['user_name'] as String,
      emailAddress: json['email_address'] as String,
      emailVerifiedAt: json['email_verified_at'] as String?,
      registeredTimestampMs: json['registered_timestamp_ms'] as int,
    );
  }

  Map<String, dynamic> toJson() {
    return {
      'user_id': userId,
      'user_name': userName,
      'email_address': emailAddress,
      'email_verified_at': emailVerifiedAt,
      'registered_timestamp_ms': registeredTimestampMs,
    };
  }

  /// Maps infrastructure wire representations to pure domain models.
  UserProfile toDomain() {
    return UserProfile(
      id: userId,
      username: userName,
      email: emailAddress,
      isVerified: emailVerifiedAt != null,
      createdAt: DateTime.fromMillisecondsSinceEpoch(
        registeredTimestampMs,
        isUtc: true,
      ),
    );
  }
}

The domain layer receives a sanitized, strongly typed UserProfile entity:

// DOMAIN LAYER: lib/features/profile/domain/entities/user_profile.dart
class UserProfile {
  const UserProfile({
    required this.id,
    required this.username,
    required this.email,
    required this.isVerified,
    required this.createdAt,
  });

  final String id;
  final String username;
  final String email;
  final bool isVerified;
  final DateTime createdAt;

  /// Business invariant encapsulated within the entity.
  bool get canPerformPrivilegedOperations => isVerified;
}

If the remote API refactors its wire contract (for example, replacing registered_timestamp_ms with an ISO-8601 string created_at), only UserProfileDto.fromJson and toDomain() must change. Not a single Use Case, ViewModel, or UI Widget requires modification.

---

3. Functional Error Handling with Dart 3 Sealed Classes

In unprincipled codebases, error handling is often left to unchecked runtime exceptions. A network client throws a SocketException, a JSON parser throws a FormatException, and a database driver throws a SqliteException. These low-level infrastructure exceptions leak up the stack, crashing widgets during layout or forcing UI controllers to wrap every call in unwieldy try/catch blocks.

In Clean Architecture, exceptions belong to infrastructure. They must be caught at the adapter boundary (the Data layer) and translated into typed Domain Failures using functional programming constructs.

Dart 3 Sealed Class Result Hierarchy

Dart 3 introduced sealed classes, providing native algebraic data types and compile-time exhaustive pattern matching. We define a generic Result<T, E> type that explicitly represents either a successful computation or a domain failure:

// CORE: lib/core/result/result.dart
sealed class Result<T, E> {
  const Result();
}

final class Success<T, E> extends Result<T, E> {
  const Success(this.data);
  final T data;
}

final class Failure<T, E> extends Result<T, E> {
  const Failure(this.error);
  final E error;
}

Next, we establish a structured domain failure hierarchy:

// DOMAIN LAYER: lib/core/error/domain_failure.dart
sealed class DomainFailure {
  const DomainFailure(this.message);
  final String message;
}

final class NetworkFailure extends DomainFailure {
  const NetworkFailure([super.message = 'Network connection unavailable. Please check your connectivity.']);
}

final class ServerFailure extends DomainFailure {
  const ServerFailure({
    required this.statusCode,
    String message = 'The remote server encountered an error.',
  }) : super(message);

  final int statusCode;
}

final class CacheFailure extends DomainFailure {
  const CacheFailure([super.message = 'Requested entity not found in local cache.']);
}

final class ValidationFailure extends DomainFailure {
  const ValidationFailure(super.message);
}

Infrastructure Exceptions vs. Domain Failures

| Condition / Exception | Originating Layer | Handled In | Mapped Domain Failure | Presentation Impact | | :--- | :--- | :--- | :--- | :--- | | SocketException / TimeoutException | HTTP Client / Network I/O | Data Layer (RepositoryImpl) | NetworkFailure | Displays offline warning or persistent retry banner. | | HttpException (HTTP 500 / 502 / 503) | Remote REST Server | Data Layer (RepositoryImpl) | ServerFailure(statusCode: 500) | Prompts user to retry after a short interval. | | FormatException / Missing Key | JSON Parser / Deserialization | Data Layer (RepositoryImpl) | ServerFailure(statusCode: 422) | Logs payload error to telemetry; displays non-crashing generic error. | | Missing Database Row | SQLite / Hive Local Cache | Data Layer (RepositoryImpl) | CacheFailure | Triggers background network refresh or empty state. | | Malformed User Input | Use Case / Interactor | Domain Layer (UseCase) | ValidationFailure | Highlights invalid input field directly in form UI. |

By catching infrastructure exceptions within the repository implementation and returning a Result<T, DomainFailure>, our method signatures become self-documenting:

// The caller is forced by the Dart type system to handle both branches.
Future<Result<UserProfile, DomainFailure>> getProfile(String userId);

---

4. Complete End-to-End Vertical Slice

To understand how these principles unify in production, let us implement a complete vertical slice: fetching a user's profile.

Architectural Flow of the Vertical Slice

[ User Tap ]
     │
     ▼
[ ProfileScreen Widget ]
     │ invokes loadProfile()
     ▼
[ ProfileNotifier (Controller) ]
     │ invokes call()
     ▼
[ GetUserProfileUseCase ]
     │ invokes getProfile()
     ▼
[ ProfileRepository (Interface) ]
     ▲
     │ implements contract
[ ProfileRepositoryImpl ]
     │ catches SocketException / FormatException
     ▼
[ ProfileRemoteDataSource ] ──> [ HTTP Network ]
     │ returns JSON
     ▼
[ UserProfileDto ] ──( .toDomain() )──> [ UserProfile Entity ]
     │
     ▼
[ Result.Success(UserProfile) ]
     │ returned up the stack
     ▼
[ ProfileNotifier: ProfileLoaded State ]
     │ notifyListeners()
     ▼
[ ProfileScreen Widget Rebuilds ]

1. Domain Layer: Entity, Repository Port, and Use Case

The Domain layer defines the business contract and execution rules with zero third-party or Flutter framework dependencies:

// lib/features/profile/domain/repositories/profile_repository.dart
import '../../../../core/error/domain_failure.dart';
import '../../../../core/result/result.dart';
import '../entities/user_profile.dart';

abstract interface class ProfileRepository {
  Future<Result<UserProfile, DomainFailure>> getProfile(String userId);
}

// lib/features/profile/domain/usecases/get_user_profile_use_case.dart
import '../../../../core/error/domain_failure.dart';
import '../../../../core/result/result.dart';
import '../entities/user_profile.dart';
import '../repositories/profile_repository.dart';

class GetUserProfileUseCase {
  const GetUserProfileUseCase(this._repository);

  final ProfileRepository _repository;

  Future<Result<UserProfile, DomainFailure>> call(String userId) async {
    final trimmedId = userId.trim();
    if (trimmedId.isEmpty) {
      return const Failure(
        ValidationFailure('User identifier cannot be empty or whitespace.'),
      );
    }

    return _repository.getProfile(trimmedId);
  }
}

2. Data Layer: Data Source, DTO, and Repository Adapter

The Data layer handles HTTP communication, catches raw I/O exceptions, and maps payloads into domain entities:

// lib/features/profile/data/datasources/profile_remote_data_source.dart
import 'dart:convert';
import 'dart:io';
import '../models/user_profile_dto.dart';

abstract interface class ProfileRemoteDataSource {
  Future<UserProfileDto> fetchProfile(String userId);
}

class ProfileRemoteDataSourceImpl implements ProfileRemoteDataSource {
  const ProfileRemoteDataSourceImpl({required this.client, required this.baseUrl});

  final HttpClient client;
  final String baseUrl;

  @override
  Future<UserProfileDto> fetchProfile(String userId) async {
    final uri = Uri.parse('$baseUrl/v1/users/$userId');
    final request = await client.getUrl(uri);
    request.headers.set('Accept', 'application/json');
    
    final response = await request.close();
    if (response.statusCode == 200) {
      final responseBody = await response.transform(utf8.decoder).join();
      final Map<String, dynamic> json = jsonDecode(responseBody) as Map<String, dynamic>;
      return UserProfileDto.fromJson(json);
    } else {
      throw HttpException('Server responded with HTTP status ${response.statusCode}');
    }
  }
}

// lib/features/profile/data/repositories/profile_repository_impl.dart
import 'dart:async';
import 'dart:io';
import '../../../../core/error/domain_failure.dart';
import '../../../../core/result/result.dart';
import '../../domain/entities/user_profile.dart';
import '../../domain/repositories/profile_repository.dart';
import '../datasources/profile_remote_data_source.dart';

class ProfileRepositoryImpl implements ProfileRepository {
  const ProfileRepositoryImpl({required this.remoteDataSource});

  final ProfileRemoteDataSource remoteDataSource;

  @override
  Future<Result<UserProfile, DomainFailure>> getProfile(String userId) async {
    try {
      final dto = await remoteDataSource.fetchProfile(userId);
      return Success(dto.toDomain());
    } on SocketException catch (e) {
      return Failure(NetworkFailure('Network unreachable: ${e.message}'));
    } on TimeoutException {
      return const Failure(NetworkFailure('Request timed out while contacting server.'));
    } on HttpException catch (e) {
      return Failure(ServerFailure(
        statusCode: 500,
        message: 'Server error: ${e.message}',
      ));
    } on FormatException catch (e) {
      return Failure(ServerFailure(
        statusCode: 422,
        message: 'Malformed response payload: ${e.message}',
      ));
    } catch (e) {
      return Failure(ServerFailure(
        statusCode: 500,
        message: 'Unexpected infrastructure failure: $e',
      ));
    }
  }
}

3. Presentation Layer: State Machine, Controller, and Reactive Widget

The Presentation layer models UI state with sealed classes and renders the interface using exhaustive pattern matching:

// lib/features/profile/presentation/state/profile_state.dart
import '../../domain/entities/user_profile.dart';

sealed class ProfileState {
  const ProfileState();
}

final class ProfileInitial extends ProfileState {
  const ProfileInitial();
}

final class ProfileLoading extends ProfileState {
  const ProfileLoading();
}

final class ProfileLoaded extends ProfileState {
  const ProfileLoaded(this.profile);
  final UserProfile profile;
}

final class ProfileError extends ProfileState {
  const ProfileError(this.message);
  final String message;
}

// lib/features/profile/presentation/controllers/profile_notifier.dart
import 'package:flutter/foundation.dart';
import '../../../../core/result/result.dart';
import '../../domain/usecases/get_user_profile_use_case.dart';
import '../state/profile_state.dart';

class ProfileNotifier extends ChangeNotifier {
  ProfileNotifier(this._getUserProfileUseCase);

  final GetUserProfileUseCase _getUserProfileUseCase;

  ProfileState _state = const ProfileInitial();
  ProfileState get state => _state;

  Future<void> loadProfile(String userId) async {
    _state = const ProfileLoading();
    notifyListeners();

    final result = await _getUserProfileUseCase(userId);

    _state = switch (result) {
      Success(:final data) => ProfileLoaded(data),
      Failure(:final error) => ProfileError(error.message),
    };
    notifyListeners();
  }
}

// lib/features/profile/presentation/pages/profile_screen.dart
import 'package:flutter/material.dart';
import '../controllers/profile_notifier.dart';
import '../state/profile_state.dart';

class ProfileScreen extends StatelessWidget {
  const ProfileScreen({
    super.key,
    required this.notifier,
    required this.userId,
  });

  final ProfileNotifier notifier;
  final String userId;

  @override
  Widget build(BuildContext context) {
    return ListenableBuilder(
      listenable: notifier,
      builder: (context, _) {
        return Scaffold(
          appBar: AppBar(title: const Text('User Profile')),
          body: switch (notifier.state) {
            ProfileInitial() => Center(
                child: ElevatedButton(
                  onPressed: () => notifier.loadProfile(userId),
                  child: const Text('Load Profile'),
                ),
              ),
            ProfileLoading() => const Center(
                child: CircularProgressIndicator(),
              ),
            ProfileLoaded(:final profile) => Padding(
                padding: const EdgeInsets.all(24.0),
                child: Column(
                  crossAxisAlignment: CrossAxisAlignment.start,
                  children: [
                    Text(
                      profile.username,
                      style: Theme.of(context).textTheme.headlineMedium,
                    ),
                    const SizedBox(height: 8),
                    Text('Email: ${profile.email}'),
                    const SizedBox(height: 8),
                    Text(
                      'Account Status: ${profile.isVerified ? "Verified" : "Pending Verification"}',
                    ),
                    const SizedBox(height: 16),
                    if (profile.canPerformPrivilegedOperations)
                      ElevatedButton(
                        onPressed: () {
                          // Perform administrative action
                        },
                        child: const Text('Access Admin Settings'),
                      ),
                  ],
                ),
              ),
            ProfileError(:final message) => Center(
                child: Padding(
                  padding: const EdgeInsets.all(24.0),
                  child: Column(
                    mainAxisSize: MainAxisSize.min,
                    children: [
                      Text(
                        message,
                        textAlign: TextAlign.center,
                        style: const TextStyle(color: Colors.red),
                      ),
                      const SizedBox(height: 16),
                      ElevatedButton(
                        onPressed: () => notifier.loadProfile(userId),
                        child: const Text('Retry'),
                      ),
                    ],
                  ),
                ),
              ),
          },
        );
      },
    );
  }
}

---

5. Dependency Injection and the Composition Root

A component must never construct its own dependencies. If GetUserProfileUseCase instantiated ProfileRepositoryImpl, the Domain layer would instantly become tightly coupled to the Data layer, violating the Dependency Inversion Principle.

Instead, dependencies must be instantiated and wired together at the Composition Root—the outermost boundary where the application bootstraps (typically main.dart or dedicated feature service modules).

COMPOSITION ROOT (main.dart / AppBootstrap)
  │
  ├── 1. Instantiate Core Infrastructure (HttpClient, Database)
  ├── 2. Instantiate Remote/Local DataSources (ProfileRemoteDataSourceImpl)
  ├── 3. Instantiate Repositories (ProfileRepositoryImpl as ProfileRepository)
  ├── 4. Instantiate Use Cases (GetUserProfileUseCase)
  └── 5. Inject into Presentation Notifiers / Widgets (ProfileNotifier)

Whether your team uses manual constructor injection, a service locator such as get_it, or dependency providers such as Riverpod, the dependency flow remains identical:

// lib/injection_container.dart
import 'dart:io';
import 'features/profile/data/datasources/profile_remote_data_source.dart';
import 'features/profile/data/repositories/profile_repository_impl.dart';
import 'features/profile/domain/repositories/profile_repository.dart';
import 'features/profile/domain/usecases/get_user_profile_use_case.dart';
import 'features/profile/presentation/controllers/profile_notifier.dart';

class ServiceLocator {
  static ProfileNotifier createProfileNotifier({required String apiBaseUrl}) {
    // 1. Data Source
    final ProfileRemoteDataSource remoteDataSource = ProfileRemoteDataSourceImpl(
      client: HttpClient(),
      baseUrl: apiBaseUrl,
    );

    // 2. Repository Implementation wired to Repository Interface
    final ProfileRepository repository = ProfileRepositoryImpl(
      remoteDataSource: remoteDataSource,
    );

    // 3. Domain Use Case
    final getUserProfileUseCase = GetUserProfileUseCase(repository);

    // 4. Presentation Notifier
    return ProfileNotifier(getUserProfileUseCase);
  }
}

During automated testing, this structure allows swapping ProfileRemoteDataSourceImpl or ProfileRepositoryImpl with in-memory test doubles without altering a single line of domain or presentation code.

---

6. Anti-Patterns and Over-Engineering Traps

Clean Architecture is a powerful tool, but when applied mechanically without pragmatic judgment, it can lead to unnecessary complexity, code bloat, and developer fatigue.

Trap 1: The Pass-Through / Anemic Use Case

An anemic use case is an interactor that does nothing except forward a parameter to a repository method:

// ❌ ANTI-PATTERN: Zero business logic, pure ceremony
class GetUserProfileUseCase {
  const GetUserProfileUseCase(this.repository);
  final ProfileRepository repository;

  Future<Result<UserProfile, DomainFailure>> call(String id) {
    return repository.getProfile(id);
  }
}

If an application features 80 standard CRUD endpoints with zero domain validation, zero coordination, and zero authorization logic, creating 80 single-line use case classes adds architectural friction without delivering value.

When to Use vs. Bypass Explicit Use Cases

| Scenario | Recommendation | Architectural Rationale | Trade-off | | :--- | :--- | :--- | :--- | | Complex Business Workflow (e.g., Checkout: validate cart, reserve inventory, process payment, generate invoice) | Use Explicit Use Case | Coordinates multiple repositories, applies validation rules, isolates complex business algorithms. | Introduces an extra class, but concentrates high-risk policies into a single, testable unit. | | Simple CRUD Read/Write (e.g., fetch static FAQ list, toggle user notification preference flag) | Bypass Use Case (Call Repository directly from ViewModel/Notifier) | No domain logic exists. A use case would merely duplicate the repository interface signature. | Removes boilerplate. If business rules emerge later, a use case can be introduced incrementally. | | Multi-Source Data Synchronization (e.g., check local SQLite cache; if expired, fetch REST API and save locally) | Encapsulate in Repository | Caching and data sync strategies are data-access concerns, not domain business rules. | Keeps the repository contract clean while shielding both use cases and presentation from storage decisions. | | Input Formatting and UI Validation (e.g., checking if email text field contains @) | Handle in Presentation | Visual feedback and keyboard event handling are presentation concerns, not enterprise business logic. | Prevents coupling core domain layers to transient UI text-field controllers. |

Trap 2: Entity-DTO Mirroring

Another common trap is blindly creating duplicate classes when an internal domain model and an external wire model have identical representations:

// Mechanical 1:1 duplication with zero distinction
class UserDto { final String id; final String name; }
class UserEntity { final String id; final String name; }

If your mobile application connects to an internal, version-controlled GraphQL or gRPC backend whose generated models already serve as clean domain representations, generating identical DTOs and manual mappers for hundreds of types is counterproductive. Establish separate DTOs when:

• the external format is volatile or controlled by third parties;
• data types differ (e.g., integer flags vs. rich Dart enums);
• domain entities enforce business invariants that raw data models cannot guarantee.

Trap 3: Treating State Management as Architecture

Teams frequently confuse state management libraries (Bloc, Riverpod, MobX) with application architecture. A team might claim: "Our app uses Bloc architecture."

State management libraries govern how UI widgets react to state changes over time. They reside entirely within the Presentation Layer. If your Bloc or Riverpod Notifier makes direct HTTP calls, runs SQL queries, and serializes JSON payloads, your codebase lacks clean architectural boundaries regardless of how reactive the UI is. State management should consume domain use cases or repositories, not replace them.

---

7. Testing Strategy Across Layer Boundaries

The ultimate metric of architectural quality is testability. In Clean Architecture, each layer is tested in isolation using the appropriate testing harness:

┌────────────────────────┬───────────────────────────┬──────────────────────┐
│ Layer                  │ Test Type                 │ Execution Speed      │
├────────────────────────┼───────────────────────────┼──────────────────────┤
│ Domain (Entities,      │ Pure Dart Unit Tests      │ Extremely Fast       │
│ UseCases)              │ (No Flutter bindings)     │ (< 1ms per test)     │
├────────────────────────┼───────────────────────────┼──────────────────────┤
│ Data (Repositories,    │ Adapter Unit Tests        │ Fast                 │
│ DataSources, DTOs)     │ (Mock HTTP / In-Memory DB)│ (5-10ms per test)    │
├────────────────────────┼───────────────────────────┼──────────────────────┤
│ Presentation           │ Flutter Widget Tests      │ Moderate             │
│ (Widgets, Notifiers)   │ (`testWidgets` binding)   │ (50-200ms per test)  │
└────────────────────────┴───────────────────────────┴──────────────────────┘

1. Domain Test: Pure Dart Unit Test

Testing a use case requires zero mocks of Flutter UI or network engines. We provide a simple in-memory fake repository:

// test/features/profile/domain/usecases/get_user_profile_use_case_test.dart
import 'package:flutter_test/flutter_test.dart';
import 'package:openstair/core/error/domain_failure.dart';
import 'package:openstair/core/result/result.dart';
import 'package:openstair/features/profile/domain/entities/user_profile.dart';
import 'package:openstair/features/profile/domain/repositories/profile_repository.dart';
import 'package:openstair/features/profile/domain/usecases/get_user_profile_use_case.dart';

class FakeProfileRepository implements ProfileRepository {
  UserProfile? stubbedProfile;
  DomainFailure? stubbedFailure;

  @override
  Future<Result<UserProfile, DomainFailure>> getProfile(String userId) async {
    if (stubbedFailure != null) {
      return Failure(stubbedFailure!);
    }
    return Success(stubbedProfile!);
  }
}

void main() {
  late FakeProfileRepository repository;
  late GetUserProfileUseCase useCase;

  setUp(() {
    repository = FakeProfileRepository();
    useCase = GetUserProfileUseCase(repository);
  });

  test('returns ValidationFailure when userId is blank', () async {
    final result = await useCase('   ');

    expect(result, isA<Failure<UserProfile, DomainFailure>>());
    final failure = (result as Failure<UserProfile, DomainFailure>).error;
    expect(failure, isA<ValidationFailure>());
    expect(failure.message, contains('cannot be empty'));
  });

  test('delegates to repository when userId is valid', () async {
    final expectedProfile = UserProfile(
      id: 'usr-100',
      username: 'asha_dev',
      email: 'asha@example.com',
      isVerified: true,
      createdAt: DateTime.utc(2025, 1, 1),
    );
    repository.stubbedProfile = expectedProfile;

    final result = await useCase('usr-100');

    expect(result, isA<Success<UserProfile, DomainFailure>>());
    final data = (result as Success<UserProfile, DomainFailure>).data;
    expect(data.username, equals('asha_dev'));
    expect(data.canPerformPrivilegedOperations, isTrue);
  });
}

---

8. Production Verification Checklist

Before releasing a Flutter application built on Clean Architecture principles, verify the codebase against this production checklist:

• [ ] Pure Dart Domain: Does the domain/ directory have zero imports of package:flutter/*, dart:io, dart:ui, or third-party database/HTTP packages?
• [ ] Strict Inward Dependencies: Do imports in domain/ point only to other domain files? Ensure no domain file imports from data/ or presentation/.
• [ ] Data Transfer Isolation: Are raw API models and database table representations (DTOs) confined to the data/ layer? Ensure zero DTOs are passed into presentation widgets.
• [ ] Explicit Exception Boundaries: Does the Data layer catch all low-level infrastructure exceptions (SocketException, TimeoutException, FormatException, HttpException, SqliteException) and convert them to typed DomainFailure instances?
• [ ] Sealed Result Outcomes: Do repository contracts and use cases return functional Result<T, DomainFailure> types rather than throwing unchecked runtime exceptions?
• [ ] Exhaustive UI Pattern Matching: Does the presentation layer consume UI states using exhaustive Dart 3 switch expressions (switch (state)) without fallback default statements?
• [ ] Pragmatic Use Cases: Are use cases reserved for meaningful domain workflows, validations, or multi-repository orchestrations, while avoiding redundant pass-through wrappers for trivial CRUD?
• [ ] Explicit Composition Root: Are dependencies injected via constructors and assembled at the application bootstrap boundary (main.dart or DI container) rather than instantiated inside consumers?
• [ ] Isolated Test Suites: Can the complete domain layer test suite execute in under two seconds on standard Dart VM bindings without initializing the Flutter engine?
• [ ] Resilient Offline Architecture: If local persistence is required, does the repository encapsulate cache retrieval and synchronization policies without leaking storage choices to the domain?

---

Conclusion

Clean Architecture is not a rigid template or a dogmatic set of directories. It is a set of boundaries that allows an engineering team to manage growth, change, and uncertainty.

By enforcing the Dependency Rule, isolating volatile external schemas behind DTO mappers, adopting functional error handling with Dart 3 sealed types, and keeping the domain pure, your Flutter application remains resilient. As backend APIs evolve, state management tooling shifts, or product requirements expand, the core business rules of your application remain stable, verifiable, and maintainable.