/layered-architecture

name: layered-architecture
description: >
  VGV layered monorepo architecture in Flutter: four layers Data, Repository, Business Logic, and
  Presentation, unidirectional dependency rules, and model transformation across layers. Use when
  structuring a multi-package Flutter app, creating data or repository packages, defining layer
  boundaries, or wiring packages in app bootstrap via path dependencies, barrel exports, and
  RepositoryProvider. Use too when asked to put a domain model or shared class in an api_client
  or data package, or to add a cross-package dependency the layers forbid. Also use for a new app
  described in one line ("I'm starting a weather app that reads from a REST API") plus a request
  for the package, project, folder, or directory layout, or for where a file or feature should
  live and which package code belongs in. Applies even when the user never says monorepo, layer,
  or architecture.
allowed-tools: Read Glob Grep mcp__very-good-cli__create mcp__very-good-cli__packages_get mcp__very-good-cli__test
effort: high

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

| Layer | Responsibility | Location | Depends On | Example | | --- | --- | --- | --- | --- | | **Data** | External communication — API calls, local storage, platform plugins | `packages/<name>_api_client/` | External packages only | `user_api_client`, `local_storage_client` | | **Repository** | Data orchestration — combines data sources, transforms models, caches | `packages/<name>_repository/` | Zero or more data layer packages | `user_repository`, `weather_repository` | | **Business Logic** | State management — processes user actions, emits state changes | `lib/<feature>/bloc/` or `lib/<feature>/cubit/` | Repository layer | `LoginBloc`, `ProfileCubit` | | **Presentation** | UI — widgets, pages, views, layout | `lib/<feature>/view/` | Business Logic layer | `LoginPage`, `ProfileView` |

┌─────────────────────────────────────────────┐
│              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_pag