Sprint review in two hours.

I opened the codebase I had been working on for the past four months. A fintech app, 23 screens deep, three developers on the team. We had moved fast. Maybe too fast.

I needed to add a new transaction filter to the payments screen. Simple enough. Except when I opened payments_screen.dart, I found API calls sitting inside initState(), a ChangeNotifier being passed down four widget levels, and a Utils class that had somehow become a graveyard for business logic that did not have anywhere else to go.

The filter took me two days. Not because it was complex. Because I spent most of that time figuring out where things lived, why they were wired the way they were, and how to add something new without breaking three other things I did not expect to touch.

That was the moment I stopped treating architecture as something you think about after the app is working.

The Turning Point

After that sprint, I started pulling apart what had gone wrong. The codebase was not messy because the developers were bad. It was messy because we had made reasonable short-term decisions that compounded into an unreasonable long-term problem.

Every initState() API call made sense at the time. Every shared ChangeNotifier was added because wiring a new one felt like overkill for one screen. Every utility dumped into utils.dart was a "I'll clean this up later" that never got cleaned up.

At 23 screens, the codebase was already giving us friction. The roadmap showed 40 more coming.

That is when I started researching, rebuilding, and eventually landing on the architecture I am going to walk you through. One I have since applied across multiple production apps in fintech, healthtech, and enterprise domains.

Why This Matters Before You Hit Screen 30

Here is the thing nobody tells you: architectural debt does not accumulate linearly. It compounds.

The 10th screen adds a little friction. The 20th adds noticeably more. By the 30th screen, every new feature is a negotiation with the decisions you made on screen 5. By the 50th, you are either doing a full rewrite or living with a codebase that actively resists change.

The symptoms show up like this. If you have worked on a mid-size Flutter project, you will recognize at least one:

• You rename a model field and have to touch 11 files

• Adding offline support to an existing feature means rewriting the entire screen

• Two developers working on different features keep breaking each other's work

• Nobody on the team can explain exactly where business logic lives

• Writing tests feels harder than writing the feature itself

None of these are Flutter problems. They are all symptoms of architecture that was built to ship, not to grow.

The fix is not working harder or being more careful. It is building a structure that makes the right thing the easy thing, every time a new screen gets added.

What We Are Going to Cover

This is not a theoretical lecture on clean architecture. It is the exact folder structure, layer separation, and wiring decisions that make a Flutter app manageable at 50+ screens. The same patterns I wish I had on that Tuesday morning.

We will cover:

• Why feature-first beats layer-first at scale

• How to separate concerns without drowning in boilerplate

• BLoC that stays clean because it delegates to UseCases

• Navigation that supports deep links and auth guards without becoming spaghetti

• Dependency injection that does not fall apart when the app doubles in size

Let us build something that ages well.

Why Architecture Breaks Down at Scale

Most Flutter tutorials teach you to build. Very few teach you to build for growth.

Here is what typically breaks down as an app scales:

• State bleeds across features. A ChangeNotifier that started life managing login state is now somehow controlling navbar visibility on screen 47.

• Navigation becomes a maze. Deeply nested Navigator.push() calls with no structure, and now you need deep linking.

• Business logic leaks into widgets. You start making API calls from initState() and it works, until the next developer needs to unit test that flow.

• Dependency management becomes tribal knowledge. Nobody knows exactly what is wired up where without tracing 4 files.

The root cause is almost always the same: features were not isolated. Everything was globally accessible, and the boundary between UI, business logic, and data was treated as a suggestion.

The Core Principle: Feature-First, Layer-Second

Most developers structure their Flutter app by layer first:

lib/
  models/
  services/
  widgets/
  screens/

This works for 10 screens. It breaks at 50 because services/ becomes a junk drawer of 30 unrelated files, and widgets/has zero context about what belongs to what.

lib/
  core/
  features/
    auth/
    dashboard/
    payments/
    profile/
  shared/

Each feature is a self-contained vertical slice. It owns its own UI, state, business logic, and data access. Nothing leaks outside its boundary unless explicitly shared.

This is not just a folder preference. It is an isolation contract. When a feature is removed, you delete one folder. When a bug is in payments, you look in one place.

The Architecture Stack

Here is the layered architecture that scales well in production Flutter apps:

+--------------------------------------+
|           Presentation Layer         |  <- Widgets, Pages, BLoC/Cubit
+--------------------------------------+
|           Domain Layer               |  <- UseCases, Entities, Repository Interfaces
+--------------------------------------+
|            Data Layer                |  <- Repository Impl, Data Sources, Models
+--------------------------------------+

This is clean architecture applied to Flutter. The rule is simple: **each layer only talks to the layer directly below it.**Widgets never call API services. Business logic never imports Flutter widgets.

Step-by-Step Implementation

1. Feature Folder Structure

Here is how a payments feature is organized:

lib/
  features/
    payments/
      data/
        datasources/
          payments_remote_datasource.dart
          payments_local_datasource.dart
        models/
          transaction_model.dart
        repositories/
          payments_repository_impl.dart
      domain/
        entities/
          transaction.dart
        repositories/
          payments_repository.dart       <- abstract interface
        usecases/
          get_transaction_history.dart
          initiate_payment.dart
      presentation/
        bloc/
          payments_bloc.dart
          payments_event.dart
          payments_state.dart
        pages/
          payments_page.dart
          transaction_detail_page.dart
        widgets/
          transaction_tile.dart

Nothing from the auth feature can be imported directly into payments. Shared utilities live in core/ or shared/.

2. Domain Layer: The Anchor of Your Architecture

The domain layer is where your business logic lives, free of any Flutter or framework dependency.

Entity (pure Dart):

class Transaction {
  final String id;
  final double amount;
  final TransactionStatus status;
  final DateTime createdAt;

  const Transaction({
    required this.id,
    required this.amount,
    required this.status,
    required this.createdAt,
  });
}

Repository Interface (abstract contract):

abstract class PaymentsRepository {
  Future<Either<Failure, List<Transaction>>>
getTransactionHistory({
    required String userId,
    int page = 1,
  });

  Future<Either<Failure, Transaction>> initiatePayment({
    required PaymentRequest request,
  });
}

Using Either<Failure, T> from the fpdart or dartz package forces explicit error handling. No more swallowed exceptions or silent null returns in UI code.

UseCase (single-responsibility business operation):

class GetTransactionHistory {
  final PaymentsRepository _repository;

  GetTransactionHistory(this._repository);

  Future<Either<Failure, List<Transaction>>> call({
    required String userId,
    int page = 1,
  }) {
    return _repository.getTransactionHistory(userId: userId, page: page);
  }
}

UseCases keep your BLoC clean and make individual operations independently testable.

3. Data Layer: Implementation Details Isolated Here

Data Model (with JSON serialization):

class TransactionModel extends Transaction {
  const TransactionModel({
    required super.id,
    required super.amount,
    required super.status,
    required super.createdAt,
  });

  factory TransactionModel.fromJson(Map<String, dynamic> json) {
    return TransactionModel(
      id: json['id'] as String,
      amount: (json['amount'] as num).toDouble(),
      status: TransactionStatus.fromString(json['status'] as String),
      createdAt: DateTime.parse(json['created_at'] as String),
    );
  }

  Map<String, dynamic> toJson() => {
    'id': id,
    'amount': amount,
    'status': status.name,
    'created_at': createdAt.toIso8601String(),
  };
}

Repository Implementation:

class PaymentsRepositoryImpl implements PaymentsRepository {
  final PaymentsRemoteDataSource _remote;
  final PaymentsLocalDataSource _local;

  PaymentsRepositoryImpl({
    required PaymentsRemoteDataSource remote,
    required PaymentsLocalDataSource local,
  })  : _remote = remote,
        _local = local;

  @override
  Future<Either<Failure, List<Transaction>>> getTransactionHistory({
    required String userId,
    int page = 1,
  }) async {
    try {
      // Offline-first: serve cache, fetch in background
      final cached = await _local.getCachedTransactions(userId);
      if (cached.isNotEmpty && page == 1) {
        _remote
          .fetchTransactions(userId: userId, page: page)
          .then((fresh) => _local.cacheTransactions(userId, fresh))
          .catchError((_) {}); // silent background refresh
        return Right(cached);
      }

      final transactions = await _remote.fetchTransactions(
        userId: userId,
        page: page,
      );
      await _local.cacheTransactions(userId, transactions);
      return Right(transactions);
    } on ServerException catch (e) {
      return Left(ServerFailure(message: e.message));
    } on CacheException catch (e) {
      return Left(CacheFailure(message: e.message));
    }
  }
}

4. Presentation Layer: BLoC Stays Thin

The BLoC's only job is to translate user events into state using UseCases. It should never contain raw HTTP calls or direct database access.

class PaymentsBloc extends Bloc<PaymentsEvent, PaymentsState> {
  final GetTransactionHistory _getTransactionHistory;

  PaymentsBloc({
    required GetTransactionHistory getTransactionHistory,
  })  : _getTransactionHistory = getTransactionHistory,
        super(const PaymentsState.initial()) {
    on<LoadTransactionHistory>(_onLoadTransactionHistory);
  }

  Future<void> _onLoadTransactionHistory(
    LoadTransactionHistory event,
    Emitter<PaymentsState> emit,
  ) async {
    emit(const PaymentsState.loading());

    final result = await _getTransactionHistory(
      userId: event.userId,
      page: event.page,
    );

    result.fold(
      (failure) => emit(PaymentsState.error(failure.message)),
      (transactions) => emit(PaymentsState.loaded(transactions)),
    );
  }
}

5. Dependency Injection: GetIt + Injectable

Do not wire dependencies manually at 50 screens. Use get_it with injectable for auto-registration.

// payments_injection.dart
@module
abstract class PaymentsModule {
  @lazySingleton
  PaymentsRemoteDataSource get remoteDataSource =>
    PaymentsRemoteDataSourceImpl(dio: getIt<Dio>());

  @lazySingleton
  PaymentsLocalDataSource get localDataSource =>
    PaymentsLocalDataSourceImpl(hive: getIt<HiveInterface>());

  @lazySingleton
  PaymentsRepository get repository => PaymentsRepositoryImpl(
    remote: getIt<PaymentsRemoteDataSource>(),
    local: getIt<PaymentsLocalDataSource>(),
  );

  @lazySingleton
  GetTransactionHistory get getTransactionHistory =>
    GetTransactionHistory(getIt<PaymentsRepository>());
}

6. Navigation: Go Router with Named Routes

At 50+ screens, Navigator.push() everywhere is unsustainable. Deep links become a nightmare. Use go_router with a centralized route registry.

// app_router.dart
final appRouter = GoRouter(
  initialLocation: '/dashboard',
  redirect: (context, state) {
    final isAuthenticated = getIt<AuthBloc>().state.isAuthenticated;
    if (!isAuthenticated && !state.location.startsWith('/auth')) {
      return '/auth/login';
    }
    return null;
  },
  routes: [
    GoRoute(path: '/auth/login', builder: (_, __) => const LoginPage()),
    ShellRoute(
      builder: (_, __, child) => MainShell(child: child),
      routes: [
        GoRoute(
          path: '/dashboard',
          builder: (_, __) => const DashboardPage(),
        ),
        GoRoute(
          path: '/payments',
          builder: (_, __) => const PaymentsPage(),
          routes: [
            GoRoute(
              path: 'transaction/:id',
              builder: (_, state) => TransactionDetailPage(
                transactionId: state.pathParameters['id']!,
              ),
            ),
          ],
        ),
      ],
    ),
  ],
);

Each feature registers its own routes. The shell handles the app scaffold (bottom nav, etc.). Deep links and auth guards work out of the box.

Best Practices

• One BLoC per screen, one BLoC per feature. Do not share a BLoC across unrelated screens. Shared state belongs in a dedicated, higher-level BLoC.

• Never pass BuildContext down to UseCases or repositories. That is a coupling smell.

• Keep models and entities separate. Models handle serialization and deserialization. Entities carry business meaning. Do not merge them.

• Use freezed for states and events. Sealed classes eliminate entire categories of state bugs.

• Abstract your data sources even if you only have one today. Swapping Firebase for REST should touch one file.

• Core utilities go in core/. Network client, error types, common extensions. Never in individual features.

• Never in individual features.

Common Mistakes and Pitfalls

1. Putting business logic in BLoC directly

dart

// Wrong: BLoC is doing repository work
on<LoadTransactions>((event, emit) async {
  final response = await dio.get('/transactions');
  final list = (response.data as List).map(TransactionModel.fromJson).toList();
  emit(PaymentsLoaded(list));
});

// Right: BLoC delegates to UseCase
on<LoadTransactions>((event, emit) async {
  final result = await _getTransactionHistory(userId: event.userId);
  result.fold(
    (f) => emit(PaymentsError(f.message)),
    (data) => emit(PaymentsLoaded(data)),
  );
});

1. Global state for everything Not every state needs to be global. A dropdown selection or form validation state should live locally in the widget. Reach for BLoC when state needs to survive navigation or be shared across screens.

2. Skipping the repository layer for simplicity When a feature is small, developers skip the repository and call the data source directly from BLoC. Three months later, you need offline support and you are refactoring the entire feature. The repository abstraction is cheap to add upfront and expensive to retrofit.

3. Naming BLoCs after screens instead of features HomeScreenBloc and ProfileScreenBloc tie your state to a view. Name them after the feature or domain instead: UserProfileBloc, FeedBloc. A BLoC can serve multiple screens.

4. Over-engineering small features A settings toggle does not need a UseCase. A local notification preference does not need a repository. Apply the full clean architecture stack to features that are complex, involve async data, or need testing. For truly simple, self-contained UI interactions, a StatefulWidget or Cubit is the right tool.

Tradeoffs: When NOT to Use This Architecture

Full clean architecture has real costs. Be honest about them:

Use this architecture when:

• The app is expected to grow beyond 20+ screens.

• Multiple developers will work on it simultaneously Long-term maintainability matters more than first-week velocity.

• The app has offline requirements or complex state flows

Do not use it when:

• You are building a prototype to validate product-market fit.

• The app is genuinely simple and will stay that way.

• The team is small and the codebase will not outlive the sprint.

The worst outcome is not using this architecture. It is applying it to every project regardless of fit.

Testing Strategy

This architecture pays its biggest dividend at test time.

• UseCases: Unit test with mocked repositories. No Flutter, no async complications.

• BLoC: Test with bloc_test package. Mock UseCases, verify state sequences.

• Repositories: Integration test by mocking data sources. Verify offline fallback logic.

• Widgets: Widget test against mocked BLoC states. No real business logic involved.

dart

// Example: unit testing a UseCase
void main() {
  late GetTransactionHistory useCase;
  late MockPaymentsRepository mockRepo;

  setUp(() {
    mockRepo = MockPaymentsRepository();
    useCase = GetTransactionHistory(mockRepo);
  });

  test('returns transactions on success', () async {
    when(() => mockRepo.getTransactionHistory(userId: 'u1'))
        .thenAnswer((_) async => Right([mockTransaction]));

    final result = await useCase(userId: 'u1');

    expect(result, Right([mockTransaction]));
  });
}

Because your business logic has zero Flutter dependencies, running this test takes milliseconds. No widget tree. No pump. No tester.

Final Recommendation

There is no universal architecture for all Flutter apps. But if you are building something that will live in production for more than 6 months, serves real users, and will be maintained by more than one person, the feature-first clean architecture approach is the most battle-tested pattern available in the Flutter ecosystem.

The summary:

• Isolate features as vertical slices

• Separate concerns across Presentation, Domain, and Data layers

• Use BLoC/Cubit for state, restricted to consuming UseCases

• Use GoRouter for scalable navigation with auth guards and deep linking

• Wire everything with GetIt + injectable, no manual DI at scale

• Apply the full stack where it is warranted; use Cubit or local state where it is not

Your architecture is a long-term bet. Make it one you will be comfortable living with when the product doubles in size.