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