Layer-Based Clean Architecture

Priority: P0 (CRITICAL)

Standardized separation of concerns and dependency flow using DDD principles.

Workflow: Add a New Feature Across Layers

1. Define the domain entity with @freezed in lib/domain/entities/
2. Define the repository interface in lib/domain/repositories/
3. Create the DTO in lib/infrastructure/dtos/ with fromJson/toEntity mapper
4. Implement the repository in lib/infrastructure/repositories/
5. Wire the BLoC/Cubit in lib/application/ consuming the repository interface
6. Register bindings in get_it injection container
7. Build the 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; do 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 a .g.dart or Data class directly in a Widget.
• No Material in Domain: Do not import package:flutter/material.dart in the domain layer.
• No Shared Prefs in Repo: Do not use shared_preferences directly in a Repository; use a Data Source.

Reference & Examples

For full implementation templates and DTO-to-Domain mapping examples: See references/REFERENCE.md.

Related Topics

feature-based-clean-architecture | bloc-state-management | dependency-injection | error-handling