Guides VGV layered monorepo architecture for Flutter apps using four layers—Data, Repository, Business Logic, Presentation—with unidirectional dependencies. Use for multi-package structuring, layer boundaries, and dependency wiring.
npx claudepluginhub verygoodopensource/very_good_claude_code_marketplace --plugin vgv-ai-flutter-pluginThis skill is limited to using the following tools:
Layered monorepo architecture for Flutter apps — four layers organized as independent Dart packages with strict unidirectional dependencies.
Applies layered architecture to Flutter apps: UI (MVVM Views/ViewModels), Data (Repositories/Services), optional Domain (Use Cases). Use for new projects or refactoring for scalability.
Provides expert Flutter/Dart patterns for cross-platform mobile apps including feature-first project structure, const widget best practices, and Riverpod/Bloc state management.
Provides Flutter/Dart guidance on architecture (BLoC, Riverpod), state management, widgets, navigation (GoRouter), data (Dio, Hive), performance, and testing for cross-platform mobile apps.
Share bugs, ideas, or general feedback.
Layered monorepo architecture for Flutter apps — four layers organized as independent Dart packages with strict unidirectional dependencies.
Apply these standards to ALL layered architecture work:
packages/ — each is an independent Dart package with its own pubspec.yamllib/ — organized by feature within the appvery_good_cli MCP server create dart_package tooluser_repository, weather_repository, auth_repositorygit: or pub version references for packages in the same reposrc/ is never imported directly by consumersmain_<flavor>.dart creates clients and repositories, provides them via RepositoryProvider| 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/ | 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/) │
└─────────────────────────────────────────────┘
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
│ │ ├── profile.dart
│ │ ├── cubit/
│ │ │ ├── profile_cubit.dart
│ │ │ └── profile_state.dart
│ │ └── view/
│ │ ├── profile_page.dart
│ │ └── profile_view.dart
│ ├── 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
│ │ ├── lib/
│ │ │ ├── local_storage_client.dart
│ │ │ └── src/
│ │ │ └── local_storage_client.dart
│ │ └── pubspec.yaml
│ ├── 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
│ ├── lib/
│ │ ├── user_repository.dart
│ │ └── src/
│ │ ├── user_repository.dart
│ │ └── models/
│ │ ├── models.dart
│ │ └── user_profile.dart
│ └── pubspec.yaml
├── test/
│ └── ... # Mirrors lib/ structure
└── pubspec.yaml # Root app pubspec
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:
very_good_cli MCP server create dart_package toolfromJson / toJson factoriessrc/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.
The repository layer orchestrates data sources and exposes domain models. Each repository composes one or more data clients, transforms response models into domain models, and provides a clean API for the business logic layer.
Rules:
very_good_cli MCP server create dart_package toolDomain 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 User extends Equatable {
const User({
required this.id,
required this.email,
required this.displayName,
this.avatarUrl,
});
final String id;
final String email;
final String displayName;
final String? avatarUrl;
@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.
Each layer's pubspec.yaml enforces the architecture through path dependencies.
packages/user_api_client/pubspec.yaml)dependencies:
# External packages only — no local dependencies
http: ^1.4.0
json_annotation: ^4.9.0
packages/user_repository/pubspec.yaml)dependencies:
equatable: ^2.0.7
# Path dependency on data layer package
user_api_client:
path: ../user_api_client
pubspec.yaml)dependencies:
flutter:
sdk: flutter
flutter_bloc: ^9.1.0
# Repository packages only — data packages are transitive
auth_repository:
path: packages/auth_repository
user_repository:
path: packages/user_repository
The app never depends on data packages directly. Data packages are transitive dependencies through repositories. This enforces the layer boundary — business logic and presentation cannot bypass the repository layer.
Step-by-step walkthrough: user taps "Load Profile" button.
context.read<ProfileBloc>().add(ProfileLoadRequested(userId: '123'))_userRepository.getUser(event.userId) and emits state based on the resultUserRepository.getUser delegates to _userApiClient.getUser and transforms the response into a domain UserUserApiClient.getUser makes the HTTP request and returns a typed UserResponseBlocBuilder based on the new state// lib/profile/bloc/profile_bloc.dart
Future<void> _onLoadRequested(
ProfileLoadRequested event,
Emitter<ProfileState> emit,
) async {
emit(const ProfileState.loading());
try {
final user = await _userRepository.getUser(event.userId);
emit(ProfileState.success(user: user));
} on UserNotFoundException {
emit(const ProfileState.notFound());
} catch (_) {
emit(const ProfileState.failure());
}
}
See data-flow.md for the full data flow walkthrough with code at each layer.
The app's main_<flavor>.dart creates all data clients and repositories, then passes them to the App widget. MultiRepositoryProvider makes repositories available to the entire widget tree.
lib/main_development.dart
import 'package:flutter/material.dart';
import 'package:my_app/app/app.dart';
import 'package:auth_api_client/auth_api_client.dart';
import 'package:local_storage_client/local_storage_client.dart';
import 'package:auth_repository/auth_repository.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);
final localStorageClient = LocalStorageClient();
// Repository layer
final authRepository = AuthRepository(
authApiClient: authApiClient,
localStorageClient: localStorageClient,
);
final userRepository = UserRepository(
userApiClient: userApiClient,
);
runApp(
App(
authRepository: authRepository,
userRepository: userRepository,
),
);
}
Flavors change only the configuration (base URLs, API keys) — the architecture stays identical across development, staging, and production. See worked-example.md for the App widget with MultiRepositoryProvider.
| Anti-Pattern | Problem | Correct Approach |
|---|---|---|
| Widget calls API client directly | Bypasses Repository and Business Logic layers — no transformation, no state management | Widget dispatches event → Bloc calls Repository → Repository calls API client |
| Repository imports another repository | Creates circular or tangled dependency graphs — breaks independent testability | Each repository is self-contained; combine data at the Bloc level if needed |
| Domain models in data layer | Couples external API shape to internal domain — API changes break the entire app | Data layer has response models; Repository layer has domain models with transformation |
| Business logic in repository | Repository becomes untestable monolith mixing orchestration with rules | Repository transforms data; Bloc/Cubit contains all business rules |
git: or pub version for local packages | Breaks monorepo — changes require publish/push cycles instead of instant local edits | Use path: dependencies for all packages within the monorepo |
| Flutter imports in data/repository packages | Prevents packages from being used in Dart-only contexts (CLI tools, servers) | Scaffold with the very_good_cli MCP server create dart_package tool — no Flutter SDK dependency |
| One giant repository for everything | God-object with too many responsibilities — impossible to test in isolation | One repository per domain boundary (user_repository, settings_repository) |
Importing src/ directly | Breaks encapsulation — consumers depend on internal structure | Export public API through barrel files; import the package, never src/ paths |
very_good_cli MCP server create dart_package tool: <name>_api_client --output-directory packagespubspec.yaml (e.g., http, json_annotation)lib/src/models/ with fromJson/toJsonlib/src/models/models.dart exporting all modelslib/src/<name>_api_client.dartlib/<name>_api_client.dart exporting src/ contentstest/ mirroring lib/ structure — see the testing skillvery_good_cli MCP server tool test from the package directoryvery_good_cli MCP server create dart_package tool: <name>_repository --output-directory packagespubspec.yamlequatable to dependencies for domain modelslib/src/models/ extending Equatablelib/src/models/models.dartlib/<name>_repository.dartpubspec.yamlmain_<flavor>.dart and pass it to AppRepositoryProvider.value in App's MultiRepositoryProviderBlocProvider and BlocBuilder — see the bloc skillvery_good_cli MCP server create dart_package tool