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

Priority Category Impact Prefix

1 Dependency Direction CRITICAL dep-

2 Entity Design CRITICAL entity-

3 Use Case Isolation HIGH usecase-

4 Component Cohesion HIGH comp-

5 Boundary Definition MEDIUM-HIGH bound-

6 Interface Adapters MEDIUM adapt-

7 Framework Isolation MEDIUM frame-

8 Testing Architecture LOW-MEDIUM test-

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

File Description

references/_sections.md Category definitions and ordering

assets/templates/_template.md Template for new rules

metadata.json Version and reference information