Feature-Based Clean Architecture Skill

Feature-Based Clean Architecture

Priority: P0 (CRITICAL)

Modular Clean Architecture organized by business features in lib/features/.

Structure

Every feature lives in lib/features/ with 3-layer separation (domain/data/presentation):

domain/ — Entities, failures, and Repository interfaces.
data/ — DTOs, DataSource, and Repository implementations.
presentation/ — BLoC/Cubit, pages, and widgets.

See references/folder-structure.md for the complete directory blueprint.

Implementation Workflow

Create feature directory — Add a new folder under lib/features/ (e.g., lib/features/promotions/).
Define domain layer — Add entities, failures, and repository interfaces with zero external dependencies.
Implement data layer — Add DTOs, data sources, and repository implementations that depend only on Domain.
Build presentation layer — Add BLoC/Cubit, pages, and widgets that depend only on Domain.
Enforce dependency rule — Presentation -> Domain <- Data. Domain must have zero external dependencies.
Share cross-cutting logic — Move reusable utilities to lib/shared/ or lib/core/.

Feature Directory Example

lib/features/orders/
├── domain/
│   ├── entities/order.dart
│   ├── failures/order_failure.dart
│   └── repositories/i_order_repository.dart
├── data/
│   ├── models/order_dto.dart
│   ├── data_sources/order_remote_data_source.dart
│   └── repositories/order_repository_impl.dart
└── presentation/
    ├── bloc/order_bloc.dart
    └── pages/order_list_page.dart

Cross-Feature Import Rule

See implementation examples for correct vs incorrect cross-feature import patterns.

Reference & Examples

For feature folder blueprints and cross-layer dependency templates: See references/REFERENCE.md.

Anti-Patterns

❌ import '…/features/orders/data/models/order_dto.dart' from another feature — only import Domain types across features
❌ lib/features/orders/domain/widgets/ — never put UI or Data classes inside Domain
❌ lib/features/orders/sub_orders/ — keep lib/features/ flat; no nested feature directories
❌ Calling another feature's repository directly from Presentation — route through that feature's BLoC or use-case

Agent Skills: Feature-Based Clean Architecture

Install this agent skill to your local

Skill Files