Flutter Lesson 73 of 83 4 min read

Flutter App Architecture: Layers and Folder Structure

Structure a Flutter app with clear layers and a feature-first folder layout: UI, logic and data, and the rules for what depends on what.

Architecture is deciding where code goes and what may depend on what. A good structure means that when you change how data is stored, no screen has to change, and when a designer moves a button, no business rule is touched.

The problem #

A screen written the quick way does everything:

class _OrdersPageState extends State<OrdersPage> {
  List<Order> _orders = [];

  Future<void> _load() async {
    final response = await http.get(Uri.parse('https://api.example.com/orders'));  // networking
    final list = jsonDecode(response.body) as List;                                // parsing
    final orders = list.map((e) => Order.fromJson(e)).toList();
    orders.removeWhere((o) => o.isCancelled);                                      // business rule
    final prefs = await SharedPreferences.getInstance();                           // caching
    await prefs.setString('orders', response.body);
    setState(() => _orders = orders);                                              // UI state
  }
  // ...and the build method
}

It works. It also cannot be tested without a server, cannot be reused by another screen, and mixes five reasons to change into one file.

Two layers, four kinds of class #

┌──────────────────────────── UI layer ─────────────────────────────┐
│  View        widgets: what the user sees and touches              │
│  ViewModel   the screen's state and the actions it offers         │
└───────────────────────────────┬───────────────────────────────────┘
                                │ calls
┌──────────────────────────── Data layer ───────────────────────────┐
│  Repository  the single source of truth for one kind of data      │
│  Service     talks to one outside system: an API, a database      │
└───────────────────────────────────────────────────────────────────┘

The models (Order, User, Product) are plain immutable classes used by every layer.

The dependency rule #

Dependencies point downwards only.

• A view never calls a service or a repository directly.
• A repository never imports a widget.
• A service knows nothing about the rest of the app.

Following this one rule gives you most of the benefit. You can replace the API with a different one by changing a service. You can test a view model with a fake repository. You can redesign a screen without reading any data code.

Folder structure #

Group by feature first, then by layer inside the feature.

lib/
  main.dart                     # entry point: creates dependencies, runs the app
  app.dart                      # MaterialApp, theme, router

  features/
    orders/
      data/
        order_api.dart          # service
        order_repository.dart   # repository
      domain/
        order.dart              # model
      ui/
        orders_page.dart        # view
        orders_view_model.dart  # view model
        widgets/
          order_tile.dart
    auth/
      data/
      domain/
      ui/

  core/
    network/
      api_client.dart           # shared HTTP setup
    storage/
      key_value_store.dart
    theme/
      app_theme.dart
    widgets/                    # widgets shared by several features
      error_view.dart
      primary_button.dart
    utils/
      formatters.dart

test/
  features/
    orders/
      order_repository_test.dart
      orders_view_model_test.dart
      orders_page_test.dart

Everything about orders is in one folder. Deleting a feature means deleting a folder. Two developers working on different features rarely touch the same files.

The alternative, layer-first (lib/models/, lib/screens/, lib/services/), is fine for a small app and common in tutorials. In a large app, one feature ends up spread across six distant folders.

What is the “domain” layer? #

Some architectures add a third layer between UI and data, holding use cases: one class per business operation, such as PlaceOrder or GetNearbyShops. It is useful when:

• Logic combines several repositories.
• The same logic is needed by several view models.
• The rules are complicated enough to deserve their own tests.

For most apps, start without it. Add a use case when a view model starts to contain logic that another screen also needs.

Naming #

Pick one set and use it everywhere. Consistency lets anyone find a file without searching.

How much is enough? #

Do not build the third for an app that needs the first. Structure should grow with the app, and moving code into layers later is straightforward.

Signs the structure is working #

• You can describe where any piece of code lives without looking.
• A change to the API touches files in data/ only.
• View models can be tested without Flutter widgets.
• Views contain almost no if statements about business rules.
• New features follow the same pattern as existing ones.

The next lesson builds one feature this way, end to end.

Try it yourself #

Take an app you built earlier in the course and sort its code into four groups: views, state, repositories and services. Write down each place where a widget makes a network call or reads storage directly. Those are the lines to move first.