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.
| Layer | Contains | May import |
|---|---|---|
| Domain | Entities, repository interfaces, use cases | Dart only |
| Data | DTOs, API clients, local DB, repository implementations | Domain, packages (Dio, sqflite) |
| Presentation | Pages, widgets, BLoC/Cubit/providers | Domain (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.
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
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.
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:
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
- DTOs leaking into widgets. The UI should render entities only.
- A fat repository interface that every feature has to implement. See SOLID principles in Dart.
- 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.