Clean Architecture Best Practices

Comprehensive guide to Clean Architecture principles for designing maintainable, testable software systems. Based on Robert C. Martin's "Clean Architecture: A Craftsman's Guide to Software Structure and Design." Contains 42 rules across 8 categories, prioritized by architectural impact.

When to Apply

Reference these guidelines when:

• •Designing new software systems or modules
• •Structuring dependencies between layers
• •Defining boundaries between business logic and infrastructure
• •Reviewing code for architectural violations
• •Refactoring coupled systems toward cleaner structure

Rule Categories by Priority

Quick Reference

1. Dependency Direction (CRITICAL)

• •dep-inward-only - Source dependencies point inward only
• •dep-interface-ownership - Interfaces belong to clients not implementers
• •dep-no-framework-imports - Avoid framework imports in inner layers
• •dep-data-crossing-boundaries - Use simple data structures across boundaries
• •dep-acyclic-dependencies - Eliminate cyclic dependencies between components
• •dep-stable-abstractions - Depend on stable abstractions not volatile concretions

2. Entity Design (CRITICAL)

• •entity-pure-business-rules - Entities contain only enterprise business rules
• •entity-no-persistence-awareness - Entities must not know how they are persisted
• •entity-encapsulate-invariants - Encapsulate business invariants within entities
• •entity-value-objects - Use value objects for domain concepts
• •entity-rich-not-anemic - Build rich domain models not anemic data structures

3. Use Case Isolation (HIGH)

• •usecase-single-responsibility - Each use case has one reason to change
• •usecase-input-output-ports - Define input and output ports for use cases
• •usecase-orchestrates-not-implements - Use cases orchestrate entities not implement business rules
• •usecase-no-presentation-logic - Use cases must not contain presentation logic
• •usecase-explicit-dependencies - Declare all dependencies explicitly in constructor
• •usecase-transaction-boundary - Use case defines the transaction boundary

4. Component Cohesion (HIGH)

• •comp-screaming-architecture - Structure should scream the domain not the framework
• •comp-common-closure - Group classes that change together
• •comp-common-reuse - Avoid forcing clients to depend on unused code
• •comp-reuse-release-equivalence - Release components as cohesive units
• •comp-stable-dependencies - Depend in the direction of stability

5. Boundary Definition (MEDIUM-HIGH)

• •bound-humble-object - Use humble objects at architectural boundaries
• •bound-partial-boundaries - Use partial boundaries when full separation is premature
• •bound-boundary-cost-awareness - Weigh boundary cost against ignorance cost
• •bound-main-component - Treat main as a plugin to the application
• •bound-defer-decisions - Defer framework and database decisions
• •bound-service-internal-architecture - Services must have internal clean architecture

6. Interface Adapters (MEDIUM)

• •adapt-controller-thin - Keep controllers thin
• •adapt-presenter-formats - Presenters format data for the view
• •adapt-gateway-abstraction - Gateways hide external system details
• •adapt-mapper-translation - Use mappers to translate between layers
• •adapt-anti-corruption-layer - Build anti-corruption layers for external systems

7. Framework Isolation (MEDIUM)

• •frame-domain-purity - Domain layer has zero framework dependencies
• •frame-orm-in-infrastructure - Keep ORM usage in infrastructure layer
• •frame-web-in-infrastructure - Web framework concerns stay in interface layer
• •frame-di-container-edge - Dependency injection containers live at the edge
• •frame-logging-abstraction - Abstract logging behind domain interfaces

8. Testing Architecture (LOW-MEDIUM)

• •test-tests-are-architecture - Tests are part of the system architecture
• •test-testable-design - Design for testability from the start
• •test-layer-isolation - Test each layer in isolation
• •test-boundary-verification - Verify architectural boundaries with tests

How to Use

Read individual reference files for detailed explanations and code examples:

• •Section definitions - Category structure and impact levels
• •Rule template - Template for adding new rules

Reference Files