Back to Blog

How I Structure a Flutter App: Feature-First Layers and Separation of Concerns

Dev Notes · Published November 17, 2026

Most Flutter apps I take over have the same problem: everything works, but nobody wants to touch it. Screens call the API directly, models are parsed in three different places, and a change to one feature breaks two others.

This is the structure I use to avoid that. It comes from Sundry, a bookkeeping app I build and ship myself: about 650 Dart files across 25 features, with a Supabase backend, AI receipt scanning, PDF invoices and subscriptions. It’s big enough that structure matters, and the same pattern works for a 20-screen client app.

The state management side (Riverpod, Freezed, build_runner) has its own post: Riverpod + Freezed + build_runner: my setup.

Feature-first, not layer-first

A layer-first app looks like this:

lib/
├── models/
├── screens/
├── services/
└── widgets/

It’s fine for 5 screens. At 50, screens/ has 80 files, one feature is spread across four folders, and nothing stops invoice_screen.dart from importing a private helper from receipt_service.dart.

Feature-first groups by what the app does:

lib/
├── main.dart
├── features/
│   ├── auth/
│   ├── businesses/
│   ├── clients/
│   ├── invoicing/
│   ├── quotes/
│   ├── receipts/
│   ├── reports/
│   ├── statements/
│   ├── subscription/
│   ├── ...
│   └── shared/        # domain types several features use (Result, etc.)
└── shared/
    ├── config/        # env, feature flags
    ├── errors/        # error → user message mapping
    ├── l10n/
    ├── router/        # go_router setup
    ├── session/
    ├── theme/         # colors, typography, spacing
    ├── ui/            # app-wide widgets: empty state, error state, dialogs
    └── util/

Each feature is a folder you can open and understand on its own. A new developer can work on quotes/ without reading statements/.

Inside a feature: three layers

Every feature that talks to a backend has the same shape:

features/clients/
├── domain/
│   ├── entities/
│   │   ├── client.dart          # Freezed model
│   │   └── client_draft.dart    # what the form sends
│   └── facade/
│       └── client_repository.dart   # abstract interface
├── data/
│   ├── repo/
│   │   └── supabase_client_repository.dart
│   └── services/                # parsing, PDF, file handling...
└── presentation/
    ├── providers/
    │   └── client_providers.dart    # Riverpod notifiers
    ├── view_models/                 # view-only state classes
    └── view/
        ├── client_detail_screen.dart
        └── client_edit_screen.dart

Domain: what the feature is

  • Entities: immutable Freezed models (Client, Invoice, Expense). They know nothing about Flutter or the database.
  • Facade: the repository interface. It says what the feature can do (list, create, delete), not how.
  • Business rules as plain Dart: “is this invoice overdue”, “which expenses count in totals”. These are the easiest things in the app to unit test, so they go here, not in widgets.

The domain layer imports nothing from data/ or presentation/, and no Flutter widgets.

Data: how it talks to the outside world

  • Repository implementations: SupabaseClientRepository implements ClientRepository. All the SQL, HTTP and storage calls live here.
  • Services: anything that transforms data: PDF rendering, image compression, file parsing.
  • Errors stop here. Every repository method returns a Result<T>, and the try/catch is in this layer only. Providers and widgets never see a raw exception.

If I ever move from Supabase to another backend, this is the only folder that changes.

Presentation: what the user sees

  • Providers: Riverpod notifiers that load data through the repository interface and expose state to the UI. This is where screen logic lives: “after saving, add it to the list”, “reload when the active business changes”.
  • View models: small classes that shape data for one screen, so widgets don’t do calculations.
  • Views: screens and widgets. They watch providers and call notifier methods. That’s it.

The dependency rule

Arrows only point one way:

presentation  →  domain  ←  data
  • Presentation depends on the domain (entities, the repository interface).
  • Data depends on the domain (it implements the interface).
  • Domain depends on nothing.

The one place they meet is the provider that builds the repository:

@riverpod
ClientRepository clientRepository(Ref ref) {
  final business = ref.watch(activeBusinessProvider);
  return SupabaseClientRepository(ref.watch(supabaseProvider), business.id);
}

The return type is the interface. Everything else in the app asks for a ClientRepository and never knows it’s Supabase. In tests I override this one provider with a mock and the whole feature runs without a network.

One request, end to end

Here’s what happens when the user creates a client:

  1. View: ClientEditScreen validates the form and calls ref.read(clientsProvider.notifier).createClient(draft).
  2. Provider: the Clients notifier calls repository.create(draft). On success it adds the new client to its state, so the list updates without a reload.
  3. Data: SupabaseClientRepository.create inserts the row and parses the response with Client.fromJson, inside Result.guard.
  4. Back up: the view gets a Result<Client>. Success → navigate to the client page. Failure → show a message.

Each step does one job, and each can be tested without the others.

Rules I keep

These matter more than the folder names:

  1. Widgets never call repositories or the backend client. Always through a provider. This is the rule that keeps screens from turning into 2,000-line files that are impossible to test.
  2. Features don’t import each other’s data/ folders. If invoicing needs clients, it watches clientsProvider or uses the Client entity. It never touches SupabaseClientRepository.
  3. lib/shared/ never imports from features/. Shared code is the bottom of the tree.
  4. Errors become user messages in one place. A single function maps any error (offline, signed out, not found, conflict) to one human sentence. Error codes and stack traces go to the log, never to the screen.
  5. Business rules live in the domain, once. When the same rule is needed in a report total and a dashboard card, both call the same function. Two copies of a rule will drift apart.
  6. Don’t create empty layers. The splash screen feature has only presentation/. A feature gets data/ and domain/ when it needs them.

Around the features: the app shell

Some things aren’t a feature. They wrap the whole app, so main.dart sets them up in order:

load env → Firebase → Supabase
  └─ SessionScope      (ProviderScope, rebuilt fresh when the user changes)
      └─ MaterialApp.router
          └─ BootGate      (wait for startup data, replay deep links)
              └─ BiometricGate
                  └─ UpdateGate

SessionScope is worth copying: when the signed-in user changes, it throws away the whole ProviderContainer and starts a fresh one. No provider can leak one user’s data to the next, and I never have to remember to reset each provider on sign-out.

When this is overkill

  • A prototype or a few screens with no backend: use feature folders only. Skip the layers.
  • A feature that only shows static content (onboarding, a guide): presentation/ only.
  • Use-case classes per action (CreateClientUseCase): I don’t use them. In Flutter, a Riverpod notifier already orchestrates the steps, and an extra class per action doubles the file count without making anything clearer.

The structure should make the next change easy. If a layer isn’t doing that for a feature, leave it out.

Takeaways

  • Group by feature first, then split each feature into domain, data, presentation.
  • Dependencies point toward the domain. The only place they meet is the repository provider.
  • Keep exceptions in the data layer, and turn errors into user messages in one place.
  • Widgets watch providers. They never call the backend.

Taking over an app that grew without a structure? That’s a lot of what I do. See how a takeover works, or get in touch.