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