flutter-app-architecture — Claude Code skill: how to install
flutter-app-architecture enforces layered Flutter architecture with MVVM, repositories, services, and unidirectional data flow.
MIT ★ 674 updated 2026-10-29
/plugin marketplace add evanca/flutter-ai-rules
/plugin install flutter-ai-skills@flutter-ai-rulesWhat flutter-app-architecture does
This skill guides the AI assistant when structuring Flutter apps into UI and Data layers, with an optional Domain layer for complex business logic. It restricts layer interactions strictly to adjacent tiers, meaning widgets never touch API services directly.
Repositories serve as the single source of truth and remain the only classes permitted to mutate data. State flows downward to views via read-only getters and ChangeNotifier, while user actions travel upward through explicit ViewModel methods.
All dependencies pass through constructors behind abstract interfaces to simplify unit testing. Skipping repository boundaries or mutating states directly inside views breaks the enforced architectural checks.
What it helps with
- Scaffold a feature into View, ViewModel, Repository, and Service layers
- Configure constructor-based dependency injection with abstract interfaces
- Implement offline caching using local storage engines like drift or sqflite
- Extract cross-cutting business rules into a dedicated Use Case
Example prompts for the agent
- Scaffold the booking feature following the layered architecture guidelines
- Implement BookingRepository with local caching and error handling
- Create a Use Case that merges data from UserRepository and BookingRepository
How to install flutter-app-architecture
1Plugin marketplace
/plugin marketplace add evanca/flutter-ai-rules/plugin install flutter-ai-skills@flutter-ai-rulesThis installs the whole flutter-ai-skills plugin with all its skills
2Skills CLI (Vercel)
npx skills add evanca/flutter-ai-rules --skill flutter-app-architecture -a claude-code3Manually: put the files in place
~/.claude/skills/flutter-app-architecture/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/flutter-app-architecture/
1Skills CLI (Vercel)
npx skills add evanca/flutter-ai-rules --skill flutter-app-architecture -a codex2Manually: put the files in place
.agents/skills/flutter-app-architecture/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add evanca/flutter-ai-rules --skill flutter-app-architecture -a cursor2Manually: put the files in place
.cursor/skills/flutter-app-architecture/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install evanca/flutter-ai-rules skills/flutter-app-architecture2Manually: put the files in place
.github/skills/flutter-app-architecture/SKILL.md1Skills CLI (Vercel)
npx skills add evanca/flutter-ai-rules --skill flutter-app-architecture -a gemini-cli2Platform CLI
gemini skills install https://github.com/evanca/flutter-ai-rules --path skills/flutter-app-architectureManually: put the files in place
.devin/skills/flutter-app-architecture/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about flutter-app-architecture
How to install flutter-app-architecture in Claude Code?
Register the marketplace and install the package by running /plugin marketplace add evanca/flutter-ai-rules followed by /plugin install flutter-ai-skills@flutter-ai-rules.
What does flutter-app-architecture do?
It provides architectural constraints for Flutter codebases, covering MVVM separation, unidirectional state management, constructor injection, and storage strategies.
When does the skill require a separate Domain layer?
Use cases are reserved for complex logic that spans multiple view models or requires orchestrating data from more than one repository.
Source text
SKILL.md · MIT
---
name: flutter-app-architecture
description: "Use when scaffolding a project, refactoring into layers, creating view models/repositories, configuring dependency injection, or implementing unidirectional data flow (MVVM)."
license: MIT
---
# Flutter App Architecture Skill
This skill defines how to structure Flutter applications using layered architecture, proper data flow, and MVVM patterns for maintainability and testability.
## When to Use
Use this skill when:
* Scaffolding a new Flutter project with layered architecture.
* Creating or refactoring View Models, Repositories, or Services.
* Wiring dependency injection between architectural components.
* Implementing unidirectional data flow across layers.
* Adding a Domain (Logic) Layer for complex business logic or shared use cases.
---
## 1. Layer Structure
Separate every app into a **UI Layer** and a **Data Layer**. Add a **Logic (Domain) Layer** only for complex apps.
```
┌──────────────────────────────────────────────────────────────┐
│ UI Layer │ Views + ViewModels │
├──────────────────────────────────────────────────────────────┤
│ Logic Layer │ Use Cases / Interactors (optional) │
├──────────────────────────────────────────────────────────────┤
│ Data Layer │ Repositories + Services │
└──────────────────────────────────────────────────────────────┘
```
**Rules:**
- Only adjacent layers may communicate. The UI layer must never access a Service directly.
- Data changes always happen in the Data layer (SSOT = Repository). No mutation in UI or Logic layers.
- Follow unidirectional data flow: state flows **down** (Data → UI), events flow **up** (UI → Data).
---
## 2. Component Responsibilities
### View
- Describes how to present data; keep logic minimal and UI-related only.
- Passes events to the ViewModel in response to user interactions.
### ViewModel
- Converts app data into UI state and maintains the current state needed by the View.
- Exposes callbacks (commands) to the View and retrieves/transforms data from Repositories.
```dart
class BookingViewModel extends ChangeNotifier {
final BookingRepository _repo;
BookingViewModel(this._repo);
List<Booking> _bookings = [];
List<Booking> get bookings => List.unmodifiable(_bookings);
bool _isLoading = false;
bool get isLoading => _isLoading;
Future<void> loadBookings() async {
_isLoading = true;
notifyListeners();
_bookings = await _repo.getBookings();
_isLoading = false;
notifyListeners();
}
Future<void> cancelBooking(String id) async {
await _repo.cancelBooking(id);
_bookings = await _repo.getBookings();
notifyListeners();
}
}
```
### Repository (Single Source of Truth)
- The only class that may mutate its data; all other classes read from it.
- Handles caching, error handling, and data refresh logic.
- Transforms raw data from Services into domain models.
```dart
class BookingRepository {
final BookingApiService _apiService;
final BookingLocalService _localService;
BookingRepository(this._apiService, this._localService);
Future<List<Booking>> getBookings() async {
try {
final remote = await _apiService.fetchBookings();
await _localService.cacheBookings(remote);
return remote;
} catch (_) {
return _localService.getCachedBookings();
}
}
Future<void> cancelBooking(String id) async {
await _apiService.cancelBooking(id);
await _localService.removeCachedBooking(id);
}
}
```
### Service
- Wraps API endpoints and exposes asynchronous response objects.
- Isolates data-loading and holds no state.
```dart
class BookingApiService {
final http.Client _client;
BookingApiService(this._client);
Future<List<Booking>> fetchBookings() async {
final response = await _client.get(Uri.parse('/api/bookings'));
if (response.statusCode != 200) {
throw HttpException('Failed to load bookings');
}
final data = jsonDecode(response.body) as List;
return data.map((json) => Booking.fromJson(json)).toList();
}
}
```
---
## 3. Dependency Injection
Supply dependencies via constructors. Define abstract interfaces so implementations can be swapped for testing.
```dart
// Abstract interface for the repository
abstract class BookingRepository {
Future<List<Booking>> getBookings();
Future<void> cancelBooking(String id);
}
// Concrete implementation
class BookingRepositoryImpl implements BookingRepository {
final BookingApiService _api;
BookingRepositoryImpl(this._api);
@override
Future<List<Booking>> getBookings() => _api.fetchBookings();
@override
Future<void> cancelBooking(String id) => _api.cancelBooking(id);
}
```
---
## 4. Use Cases (Domain Layer)
Introduce use cases only when:
- Logic is complex or does not fit cleanly in the UI or Data layers.
- Logic is reused across multiple ViewModels or merges data from multiple Repositories.
```dart
class GetUpcomingBookingsUseCase {
final BookingRepository _bookingRepo;
final UserRepository _userRepo;
GetUpcomingBookingsUseCase(this._bookingRepo, this._userRepo);
Future<List<Booking>> call() async {
final user = await _userRepo.getCurrentUser();
final bookings = await _bookingRepo.getBookings();
return bookings
.where((b) => b.userId == user.id && b.date.isAfter(DateTime.now()))
.toList();
}
}
```
---
## 5. Workflow: Scaffold a New Feature
1. **Create the Service** — implement the API wrapper with typed response parsing.
2. **Create the Repository** — inject the Service, implement caching and error-handling logic.
3. **Create the ViewModel** — inject the Repository, expose UI state and commands.
4. **Create the View** — bind to the ViewModel, render state, dispatch events.
5. **Wire DI** — register all components in the dependency injection container.
6. **Verify** — confirm the View never accesses the Service directly and data flows unidirectionally.
---
## 6. Data Storage
- Use **key-value storage** (e.g., `shared_preferences`) for configuration and preferences.
- Use **SQL storage** (e.g., `drift`, `sqflite`) for complex relational data.
- Implement **optimistic updates** to improve perceived responsiveness by updating UI before server confirms.
- Support **offline-first** by combining local and remote data sources in Repositories.
---
## 7. Coding Conventions
- Use `StatelessWidget` when possible; avoid unnecessary `StatefulWidget`s.
- Keep build methods simple and focused on rendering.
- Prefer `final` for fields and top-level variables. Prefer `const` constructors when the class supports it.
- Prefer explicit typing on public APIs (e.g., `Command0<void>` over dynamic signatures).
- Use descriptive constant names (e.g., `_todoTableName` over `_kTableTodo`).
---
## References
- [Flutter app architecture guide](https://docs.flutter.dev/app-architecture/guide)
- [Flutter Website GitHub Repository](https://github.com/flutter/website)
© Ivanna Kaceviča · MIT · evanca/flutter-ai-rules