Flutter Clean Architecture with BLoC or Impeller Migration article

How to decouple presentation, domain invariants, and data sources in high-throughput mobile products without bloated state files.

1.

Why Standard Flutter Architecture Crumbles at Scale
Most Flutter tutorials model architecture around simple CRUD flows: a screen directly triggers an HTTP request, parses JSON in-line, and updates a local setState() or a catch-all controller. In a multi-team production app with concurrent network requests, offline caching, and deep links, this pattern rapidly collapses.
Business rules inevitably bleed into UI widgets. A change to a backend response contract forces rewrites across dozens of screen components. Worse, edge-case failure modes—such as token expiration mid-flow, cellular handovers, and rate-limited endpoints—get handled inconsistently.
Clean Architecture, originally formulated by Robert C. Martin and adapted for Flutter by the community, solves this by enforcing the Dependency Inversion Principle: the core domain never depends on Flutter UI frameworks or third-party database packages.

Key Takeaway: Domain rules (entities, use cases, business validation) must remain 100% pure Dart with zero imports from package:flutter.

2. The Three-Layer Contract: Presentation, Domain, Data

In production systems like the multi-vendor Wasey Food Delivery platform, we separate every feature module into three distinct layers:

1. Domain Layer: Contains purely immutable entities, value objects, and abstract repository contracts. It defines what the business does, not how data is transported.
2. Data Layer: Implements domain repository contracts. It orchestrates local database drivers (Hive, SQLite) and remote REST/GraphQL clients, converting raw JSON DTOs into clean Domain Entities.
3. Presentation Layer: BLoCs (Business Logic Components) and UI widgets. BLoCs consume Domain Use Cases and emit immutable UI states that widgets reactively rebuild upon.

dart
// Domain Layer: Abstract Repository Contract (Zero Flutter Dependencies)
abstract class OrderRepository {
  Future<Either<Failure, OrderEntity>> getOrderDetails(String orderId);
  Stream<OrderEntity> watchOrderLiveUpdates(String orderId);
}
// Data Layer: Concrete Implementation with Network Resilience
class OrderRepositoryImpl implements OrderRepository {
  final OrderRemoteDataSource remoteDataSource;
  final OrderLocalDataSource localDataSource;
  OrderRepositoryImpl({
    required this.remoteDataSource,
    required this.localDataSource,
  });
  @override
  Future<Either<Failure, OrderEntity>> getOrderDetails(String orderId) async {
    try {
      final model = await remoteDataSource.fetchOrder(orderId);
      await localDataSource.cacheOrder(model);
      return Right(model.toEntity());
    } on SocketException {
      // Graceful offline fallback from local disk
      final cached = await localDataSource.getLastCachedOrder(orderId);
      if (cached != null) return Right(cached.toEntity());
      return Left(NetworkFailure(message: 'No connectivity and no cache found.'));
    } on ServerException catch (e) {
      return Left(ServerFailure(message: e.message, statusCode: e.statusCode));
    }
  }
}

Data layer repository implementation mapping DTOs to Domain Entities with offline fallback.

3. Treating BLoC States as Finite State Machines
A common anti-pattern in Flutter BLoC is creating a single monolithic state with twenty optional nullable fields. This causes race conditions and unexpected widget rebuilds.

In production, every BLoC should operate as a strict Finite State Machine (FSM). For an order tracking screen, the state cannot simultaneously be 'loading' and 'completed'. Use sealed classes (or freezed unions) to declare exhaustive states: Initial, Loading, ActiveTracking, and Error.


dart
// Sealed class pattern in modern Dart 3+
sealed class OrderTrackingState {
  const OrderTrackingState();
}
class OrderTrackingInitial extends OrderTrackingState {
  const OrderTrackingInitial();
}
class OrderTrackingLoading extends OrderTrackingState {
  final String statusMessage;
  const OrderTrackingLoading({this.statusMessage = 'Connecting...'});
}
class OrderTrackingActive extends OrderTrackingState {
  final OrderEntity order;
  final LatLng driverLocation;
  final int etaMinutes;
  const OrderTrackingActive({
    required this.order,
    required this.driverLocation,
    required this.etaMinutes,
  });
}
class OrderTrackingFailure extends OrderTrackingState {
  final String errorMessage;
  final bool isRetryable;
  const OrderTrackingFailure({
    required this.errorMessage,
    this.isRetryable = true,
  });
}

Key Takeaway: When writing switch statements over sealed BLoC states, the Dart analyzer enforces compile-time handling of every possible edge case.

4. Real-World Lessons from Shipped Apps

Deploying Clean Architecture across multi-vendor logistics (Wasey) and enterprise clinical healthcare systems (Health Automated) provided three indispensable takeaways:

1. Avoid Pass-Through Use Cases: Do not create unnecessary Use Cases for trivial pass-throughs. If a repository method simply returns a stream without business transformation, exposing the repository interface directly to the BLoC avoids useless boilerplate classes.

2. Strictly Enforce DTO-to-Entity Transformations: Enforce transformation strictly at data layer boundaries. Never allow an auto-generated JSON model with string keys to leak into your UI widgets.

3. Test Business Logic in Isolation: Because our domain and BLoC layers have zero dependencies on Flutter rendering trees, we achieve 90%+ unit test coverage running in under 3 seconds in our GitHub Actions CI pipeline.

About the Author
I am Syed Waleed Nawaz, a Senior Flutter Developer & Mobile Backend Engineer with 5+ years shipping production applications across iOS, Android, and Web for US, UK, and UAE startups.

Portfolio: syedwaleednawaz.com
Need architecture consulting or Flutter app engineering? Explore my Flutter App Development Services or Contact Me