| name | flutter-layer-based-clean-architecture |
| description | Enforce inward dependency flow, pure domain layers, and DTO-to-entity mapping in Flutter DDD architecture. Use when structuring layers or boundaries; defer navigation-only routing and feature implementation such as notifications. |
| metadata | {"triggers":{"files":["lib/domain/**","lib/infrastructure/**","lib/application/**"],"keywords":["dto","mapper","Either","Failure"]}} |
Layer-Based Clean Architecture
Priority: P0 (CRITICAL)
Workflow: Add New Feature Across Layers
- Define domain entity with
@freezed in lib/domain/entities/
- Define repository interface in
lib/domain/repositories/
- Create DTO in
lib/infrastructure/dtos/ with fromJson/toEntity mapper
- Implement repository in
lib/infrastructure/repositories/
- Wire BLoC/Cubit in
lib/application/ consuming repository interface
- Register bindings in
get_it injection container
- Build screen in
lib/presentation/ using BlocBuilder
Structure
lib/
├── domain/ # Pure Dart: entities (@freezed), failures, repository interfaces
├── infrastructure/ # Implementation: DTOs, data sources, mappers, repo impls
├── application/ # Orchestration: BLoCs / Cubits
└── presentation/ # UI: Screens, reusable components
Implementation Guidelines
- Dependency Flow:
Presentation -> Application -> Domain <- Infrastructure. Dependencies point inward.
- Pure Domain: No Flutter (Material/Store) or Infrastructure (Dio/Hive) dependencies in
Domain.
- Functional Error Handling: Repositories must return
Either<Failure, Success>.
- Always Map: Infrastructure must map DTOs to Domain Entities; not leak DTOs to UI.
See DTO-to-Entity mapping example.
- Immutability: Use
@freezed for all entities and failures.
- Logic Placement: No business logic in UI; widgets only display state and emit events.
- Inversion of Control: Use
get_it to inject repository implementations into BLoCs.
Anti-Patterns
- No DTOs in UI: Never import
.g.dart or Data class directly in Widget.
- No Material in Domain: not import
package:flutter/material.dart in domain layer.
- No Shared Prefs in Repo: not use
shared_preferences directly in Repository; use Data Source.
Reference & Examples
For full implementation templates and DTO-to-Domain mapping examples:
See references/REFERENCE.md.
References
- feature-based-clean-architecture | bloc-state-management | dependency-injection | error-handling
Canonical response anchors
When this skill applies, preserve the following domain terminology or equivalent concrete examples in the answer when relevant:
