Most Flutter apps start the same way: a screen calls http.get, parses JSON inside the widget, and stores the result in a setState. It works, until the API changes, the screen needs a second data source, or you try to write a test. Clean Architecture is a way to make those changes cheap.

This is the version I actually use on production Flutter apps: not the textbook diagram, but the parts that pay for themselves.

The one rule that matters

Dependencies point inward. Your business rules (the domain) know nothing about Flutter, Dio, Supabase or JSON. The UI and the data layer depend on the domain, never the other way around.

LayerContainsMay import
DomainEntities, repository interfaces, use casesDart only
DataDTOs, API clients, local DB, repository implementationsDomain, packages (Dio, sqflite)
PresentationPages, widgets, BLoC/Cubit/providersDomain (and Flutter)

If domain/ ever imports package:dio or package:flutter, the rule is broken.

Structure by feature, not by type

Group by feature first, then by layer. A new developer can find everything about "orders" in one place.

code
lib/
  core/            # errors, Result type, network setup, theme
  features/
    orders/
      domain/
        entities/order.dart
        repositories/order_repository.dart   # abstract
        usecases/get_orders.dart
      data/
        models/order_dto.dart
        datasources/order_api.dart
        repositories/order_repository_impl.dart
      presentation/
        bloc/orders_bloc.dart
        pages/orders_page.dart

The domain: plain Dart

dart
class Order {
  const Order({required this.id, required this.total, required this.status});
  final String id;
  final double total;
  final OrderStatus status;
}

abstract interface class OrderRepository {
  Future<Result<List<Order>>> getOrders();
}

class GetOrders {
  const GetOrders(this._repository);
  final OrderRepository _repository;

  Future<Result<List<Order>>> call() => _repository.getOrders();
}

The data layer: translate at the boundary

DTOs mirror the API. Entities mirror your business. The repository converts one into the other, and turns exceptions into typed failures.

dart
class OrderRepositoryImpl implements OrderRepository {
  OrderRepositoryImpl(this._api);
  final OrderApi _api;

  @override
  Future<Result<List<Order>>> getOrders() async {
    try {
      final dtos = await _api.fetchOrders();
      return Ok(dtos.map((d) => d.toEntity()).toList());
    } on DioException catch (e) {
      return Err(Failure.fromDio(e));
    }
  }
}

The payoff: when the backend renames total_amount to grand_total, exactly one file changes. The UI never notices.

Presentation: depend on use cases

The BLoC receives a use case, not a Dio instance:

dart
class OrdersBloc extends Bloc<OrdersEvent, OrdersState> {
  OrdersBloc(this._getOrders) : super(const OrdersLoading()) {
    on<OrdersRequested>((event, emit) async {
      final result = await _getOrders();
      emit(switch (result) {
        Ok(:final value) => OrdersLoaded(value),
        Err(:final failure) => OrdersFailed(failure.message),
      });
    });
  }
  final GetOrders _getOrders;
}

How the pieces get wired together is a separate concern; see dependency injection in Flutter with get_it.

When Clean Architecture is overkill

  • A prototype or a three-screen app: use a single repository and skip use cases.
  • A use case that only forwards one call adds a file and no value. Keep use cases for real logic (combining sources, validation, rules).
  • Do not create a domain entity that is identical to a DTO "just in case" on a throwaway feature.

Start lean and add layers when the pain appears. The dependency rule is the part worth keeping from day one.

Common mistakes

  1. DTOs leaking into widgets. The UI should render entities only.
  2. A fat repository interface that every feature has to implement. See SOLID principles in Dart.
  3. Skipping tests because "it is just wiring". The payoff of this structure is how easy it makes testing Flutter apps.

Key takeaways

  • Domain depends on nothing; data and presentation depend on domain.
  • Organize by feature, then by layer.
  • Convert DTOs to entities and exceptions to failures at the data boundary.
  • Add layers when they solve a real problem, not before.

I build Flutter apps this way for a living. If you are hiring for a mobile role, see my projects or get in touch.