Layered Architecture

Layered Architecture

Layered monorepo architecture for Flutter apps — four layers organized as independent Dart packages with strict unidirectional dependencies.

Core Standards

Apply these standards to all layered architecture work:

• Four layers — Data, Repository, Business Logic, Presentation — a feature spans all four whenever its repository reads an external source
• Unidirectional dependencies — Presentation → Business Logic → Repository → Data — never skip or invert a layer
• Data and Repository layers live in packages/ — each is an independent Dart package with its own pubspec.yaml
• Business Logic and Presentation live in lib/ — organized by feature within the app
• Data layer packages contain zero domain/business logic — they must be reusable in unrelated projects
• No inter-repository dependencies — repositories never import other repositories
• No Flutter SDK in data or repository packages — scaffold with the very_good_cli MCP server create dart_package tool
• One repository per domain — user_repository, weather_repository, auth_repository
• Path dependencies for local packages — never git: or pub version references for packages in the same repo
• Barrel exports at every package boundary — src/ is never imported directly by consumers
• Repositories take every external source through the constructor — a data client or an SDK object such as FirebaseAuth.instance, built in bootstrap and passed in, never constructed or defaulted inside the repository
• App bootstrap wires all layers — main_<flavor>.dart creates clients and repositories, provides them via RepositoryProvider
• Only the app's entrypoints and bootstrap import a data package — blocs, widgets, and app tests reach data through a repository
• Dart 3.13 primary constructors — on a Dart 3.13+ baseline, declare model and widget fields as primary-constructor declaring parameters (class const User(final String id, final String name) extends Equatable) rather than this.field; keep the classic form only below 3.13

Cross-harness fallback. This skill scaffolds and tests packages via the Very Good CLI MCP server. On a host without this plugin's Bash hooks and without that MCP server connected, run the equivalent very_good create dart_package …, very_good packages get, and very_good test commands directly.

Architecture Overview

┌─────────────────────────────────────────────┐
│              Presentation                   │
│          (lib/<feature>/view/)              │
└──────────────────┬──────────────────────────┘
                   │ reads state / dispatches events
┌──────────────────▼──────────────────────────┐
│            Business Logic                   │
│        (lib/<feature>/bloc/)                │
└──────────────────┬──────────────────────────┘
                   │ calls repository methods
┌──────────────────▼──────────────────────────┐
│              Repository                     │
│      (packages/<name>_repository/)          │
└──────────────────┬──────────────────────────┘
                   │ calls data clients
┌──────────────────▼──────────────────────────┐
│               Data                          │
│     (packages/<name>_api_client/)           │
└─────────────────────────────────────────────┘

Monorepo Structure

Features live in lib/, one directory each, split bloc|cubit/ and view/ with a barrel file. Layers live in packages/, one package per data source and one per repository. The second data package and the second repository follow the same shape as the first.

my_app/
├── lib/
│   ├── app/
│   │   ├── app.dart                          # Barrel file
│   │   └── view/
│   │       └── app.dart                      # App widget with MultiRepositoryProvider
│   ├── login/                                # Feature: login
│   │   ├── login.dart                        # Barrel file
│   │   ├── bloc/
│   │   │   ├── login_bloc.dart
│   │   │   ├── login_event.dart
│   │   │   └── login_state.dart
│   │   └── view/
│   │       ├── login_page.dart               # Page provides Bloc
│   │       └── login_view.dart               # View consumes state
│   ├── profile/                              # Feature: profile
│   ├── main_development.dart                 # Flavor entrypoint
│   ├── main_staging.dart
│   └── main_production.dart
├── packages/
│   ├── auth_api_client/                      # Data layer: auth API
│   │   ├── lib/
│   │   │   ├── auth_api_client.dart          # Barrel file
│   │   │   └── src/
│   │   │       ├── auth_api_client.dart
│   │   │       └── models/
│   │   │           ├── models.dart
│   │   │           └── auth_response.dart
│   │   └── pubspec.yaml
│   ├── local_storage_client/                 # Data layer: local storage
│   ├── auth_repository/                      # Repository layer: auth
│   │   ├── lib/
│   │   │   ├── auth_repository.dart          # Barrel file
│   │   │   └── src/
│   │   │       ├── auth_repository.dart
│   │   │       └── models/
│   │   │           ├── models.dart
│   │   │           └── user.dart             # Domain model
│   │   └── pubspec.yaml
│   └── user_repository/                      # Repository layer: user
├── test/
│   └── ...                                   # Mirrors lib/ structure
└── pubspec.yaml                              # Root app pubspec

Data Layer

The data layer handles all external communication. Each data package wraps a single external source (REST API, local database, platform plugin) and exposes typed methods and response models.

Rules:

• Models represent the external data shape — match the API/storage schema exactly
• No Flutter imports — use the very_good_cli MCP server create dart_package tool
• Constructor-inject HTTP clients for testability
• Response models use fromJson / toJson factories
• Export everything through a barrel file — never expose src/

Pattern: Data Client Class

Constructor-inject the HTTP client for testability. Return typed response models — never raw JSON.

/// HTTP client for the User API.
class UserApiClient {
  // http.Client injected — tests pass a mock, production gets a real client
  UserApiClient({
    required String baseUrl,
    http.Client? httpClient,
  })  : _baseUrl = baseUrl,
        _httpClient = httpClient ?? http.Client();

  final String _baseUrl;
  final http.Client _httpClient;

  /// Every method returns a typed response model.
  Future<UserResponse> getUser(String userId) async {
    final response = await _httpClient.get(
      Uri.parse('$_baseUrl/users/$userId'),
    );
    if (response.statusCode != 200) {
      throw UserApiException(response.statusCode, response.body);
    }
    return UserResponse.fromJson(
      json.decode(response.body) as Map<String, dynamic>,
    );
  }
}

See worked-example.md for the complete user_api_client package with pubspec, barrel files, response models, and exception class.

Repository Layer

The repository layer orchestrates data sources and exposes domain models. Each repository composes the data clients it needs, transforms response models into domain models, and provides a clean API for the business logic layer.

Rules:

• No inter-repository dependencies — repositories are isolated
• No Flutter SDK — the very_good_cli MCP server create dart_package tool
• Domain models live in the repository package — not in data packages
• Transform data models into domain models — never leak API response shapes upstream
• A repository with no external source, such as in-memory session state, takes no constructor arguments

Pattern: Domain Model + Repository Transformation

Domain models extend Equatable and represent the app's internal data shape — distinct from the API response shape. The repository method transforms between them.

/// Domain model — lives in the repository package, NOT the data package.
/// Fields match the app's needs, not the API schema.
class const User({
  required final String id,
  required final String email,
  required final String displayName,
  final String? avatarUrl,
}) extends Equatable {
  @override
  List<Object?> get props => [id, email, displayName, avatarUrl];
}

/// Repository accepts data client via constructor — never creates its own.
class UserRepository {
  const UserRepository({
    required UserApiClient userApiClient,
  }) : _userApiClient = userApiClient;

  final UserApiClient _userApiClient;

  /// Transforms UserResponse (API shape) → User (domain shape).
  Future<User> getUser(String userId) async {
    final response = await _userApiClient.getUser(userId);
    return User(
      id: response.id,
      email: response.email,
      displayName: response.displayName,
      avatarUrl: response.avatarUrl,
    );
  }
}

See worked-example.md for the complete user_repository package with pubspec, barrel files, and error handling. See model-transformation.md for detailed transformation patterns between data and domain models.

Dependency Graph

Path dependencies in each pubspec.yaml point one direction. A data package declares external packages only. A repository package declares a path dependency on its data packages. The root app declares its repository packages and every data package its bootstrap constructs. main_<flavor>.dart imports each client to inject it, and depend_on_referenced_packages in package:very_good_analysis requires every imported package to be declared.

Imports hold the layer boundary. Once the app declares a data package, the lint no longer stops a bloc from importing it. The boundary is the import rule in Core Standards: only the app's entrypoints and bootstrap import a data package.

# packages/user_api_client/pubspec.yaml — external packages only
dependencies:
  http: ^1.4.0

# packages/user_repository/pubspec.yaml — path dependency on its data package
dependencies:
  user_api_client:
    path: ../user_api_client

# pubspec.yaml: repositories, plus the data packages bootstrap constructs
dependencies:
  user_api_client:
    path: packages/user_api_client
  user_repository:
    path: packages/user_repository

See references/pubspec.md for the three files in full and for checking the import boundary, including which files count as entrypoints and bootstrap.

Data Flow

Presentation dispatches an event → Bloc calls the repository → repository calls the data client and returns a domain model → BlocBuilder rebuilds on the new state.

See references/data-flow.md for the code at each layer.

App Bootstrap

main_<flavor>.dart imports and constructs every data client and repository, then passes the repositories to the App widget, which exposes them through MultiRepositoryProvider. Flavors change only configuration — base URLs, API keys — never the wiring shape.

// lib/main_development.dart
import 'package:auth_api_client/auth_api_client.dart';
import 'package:auth_repository/auth_repository.dart';
import 'package:flutter/material.dart';
import 'package:my_app/app/app.dart';
import 'package:user_api_client/user_api_client.dart';
import 'package:user_repository/user_repository.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();

  const baseUrl = 'https://api.dev.example.com';

  // Data layer
  final authApiClient = AuthApiClient(baseUrl: baseUrl);
  final userApiClient = UserApiClient(baseUrl: baseUrl);

  // Repository layer
  final authRepository = AuthRepository(authApiClient: authApiClient);
  final userRepository = UserRepository(userApiClient: userApiClient);

  runApp(
    App(
      authRepository: authRepository,
      userRepository: userRepository,
    ),
  );
}

See references/worked-example.md for the full main() and the App widget with MultiRepositoryProvider.