playbooks

home / skills / hoangnguyen0403 / agent-skills-standard / feature-based-clean-architecture

feature-based-clean-architecture skill

/skills/flutter/feature-based-clean-architecture

This skill enforces feature-based clean architecture for scalable Flutter apps by organizing by feature with strict layers and domain-first dependencies.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill feature-based-clean-architecture

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
1.6 KB
---
name: Flutter Feature-Based Clean Architecture
description: Standards for organizing code by feature at the root level to improve scalability and maintainability.
metadata:
  labels: [architecture, clean-architecture, feature-driven, ddd, modularity]
  triggers:
    files: ['lib/features/**']
    keywords:
      [feature, domain, infrastructure, application, presentation, modular]
---

# Feature-Based Clean Architecture

## **Priority: P0 (CRITICAL)**

Standard for modular Clean Architecture organized by business features in `lib/features/`.

## Structure

See [references/folder-structure.md](references/folder-structure.md) for the complete directory blueprint.

## Implementation Guidelines

- **Feature Encapsulation**: Keep logic, models, and UI internal to the feature directory.
- **Strict Layering**: Maintain 3-layer separation (Domain/Data/Presentation) within each feature.
- **Dependency Rule**: `Presentation -> Domain <- Data`. Domain must have zero external dependencies.
- **Cross-Feature Communication**: Features only depend on the **Domain** layer of other features.
- **Flat features**: Keep `lib/features/` flat; avoid nested features.
- **No DTO Leakage**: Never expose DTOs or Data Sources to UI or other features; return Domain Entities.
- **Shared logic**: Move cross-cutting concerns to `lib/shared/` or `lib/core/`.

## Reference & Examples

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

## Related Topics

layer-based-clean-architecture | retrofit-networking | go-router-navigation | bloc-state-management | dependency-injection

Overview

This skill defines a Feature-Based Clean Architecture for Flutter projects to improve scalability and maintainability by organizing code by business feature at the root level. It prescribes a three-layer separation (Presentation/Domain/Data) inside each feature and strict dependency rules to minimize coupling. The guidance enforces feature encapsulation, flat feature folders, and clear boundaries for shared logic.

How this skill works

The skill inspects project structure and enforces that each feature lives under lib/features/ with isolated Presentation, Domain, and Data layers. It checks dependency directions so Domain has no external dependencies and Presentation depends only on Domain. It flags DTO or data-source leakage to UI or other features and recommends moving cross-cutting code to lib/shared/ or lib/core/.

When to use it

  • Starting a new Flutter app that must scale across teams
  • Refactoring a monolithic codebase into modular features
  • Enforcing architecture rules in CI or code reviews
  • Onboarding teams to a consistent feature-based project layout
  • Reducing inter-feature coupling and accidental data model exposure

Best practices

  • Keep each feature self-contained: models, use cases, UI, and data live inside the feature folder
  • Enforce strict layering: Presentation -> Domain <- Data; Domain remains dependency-free
  • Keep lib/features/ flat—do not nest features under other feature folders
  • Return Domain entities to UI; never expose DTOs or data sources outside Data layer
  • Place shared utilities, widgets, and cross-cutting concerns in lib/shared/ or lib/core/ only

Example use cases

  • Create a payments feature folder with presentation widgets, domain use cases/entities, and data repositories that implement interfaces defined in domain
  • CI job that validates folder structure and dependency rules before merging
  • Refactor authentication logic from app-wide services into a self-contained auth feature
  • Document templates for feature blueprints and cross-layer interfaces for new team members
  • Implement cross-feature flows by importing only the other feature’s Domain interfaces

FAQ

What does "Domain must have zero external dependencies" mean?

The Domain layer contains pure business models and interfaces and must not import platform, framework, or data packages so it stays testable and reusable.

How do I share utilities across features?

Move cross-cutting utilities, widgets, and services into lib/shared/ or lib/core/ and keep them small and well-documented to avoid hidden coupling.