Clean Architecture

Related Skills

• Need to move code between layers? → Use refactoring for safe migration steps
• Designing the domain layer's internal structure? → Use domain-modeling for entities and aggregates
• Defining API contracts or DB schemas at boundaries? → Use schema

Applicability Rubric

Apply when: Any condition passes

Core Principles

Layer Structure

┌─────────────────────────────────────────────┐
│          Frameworks & Drivers               │  ← Web, DB, Devices, External Interfaces
├─────────────────────────────────────────────┤
│          Interface Adapters                 │  ← Controllers, Presenters, Gateways
├─────────────────────────────────────────────┤
│             Use Cases                       │  ← Application-specific Business Rules
├─────────────────────────────────────────────┤
│             Entities                        │  ← Enterprise-wide Business Rules
└─────────────────────────────────────────────┘

Dependency Rule

Dependencies MUST point inward:

• Frameworks & Drivers → Interface Adapters → Use Cases → Entities
• Entities have NO dependencies on outer layers
• Use interfaces (ports) at layer boundaries for dependency inversion

Implementation Order: Outside-In

Dependency direction (inward) and implementation order are independent concepts. Clean Architecture prescribes that dependencies point inward, but does NOT prescribe starting implementation from the inner layers.

Implement outside-in — start from the user-facing layer, work inward:

1. User need / acceptance test (E2E or integration)
   ↓
2. Interface Adapter — define controller/presenter shape
   ↓
3. Use Case — discover required application operations, define ports (interfaces)
   ↓
4. Entity — let domain model emerge from use case needs
   ↓
5. Infrastructure — defer database, ORM, and external service decisions until last

Layer Responsibilities

Entities Layer: Naming and Internal Structure

The Entities layer is a conceptual layer, not a specific directory name. Before writing code, decide how the Entities layer will be expressed in the project. This decision depends on one question: does this system benefit from DDD, or does plain Clean Architecture already model it clearly enough?

Do we need DDD on top of CA?

DDD adds vocabulary (Aggregate, Value Object, Bounded Context, Ubiquitous Language) and modelling cost. It pays off when the domain has rich invariants, non-trivial workflows, or multiple teams speaking different languages about the same nouns. It is overhead when the system is mostly CRUD with thin rules.

When in doubt, start with pure CA. Introducing DDD later is a refactor; ripping out premature DDD is a harder refactor because the vocabulary spreads into tests and conversations.

Three styles, three directory layouts

Pure CA                    CA + DDD (single)          CA + DDD (multi-context)
src/                       src/                       src/
├── entities/              ├── domain/                ├── sales/
│   ├── user.rb            │   ├── order.rb           │   ├── domain/
│   └── invoice.rb         │   ├── line_item.rb       │   └── use_cases/
├── use_cases/             │   └── money.rb           ├── shipping/
├── adapters/              ├── use_cases/             │   ├── domain/
└── infrastructure/        ├── adapters/              │   └── use_cases/
                           └── infrastructure/        └── billing/
                                                          ├── domain/
                                                          └── use_cases/

Do not mix the styles by accident. The most common mistake is defaulting to domain/ because DDD vocabulary feels more "professional", even when the project has no aggregates and no ubiquitous-language conflicts. If you cannot name an aggregate or an invariant the directory is enforcing, use entities/ and plain CA — it is not a downgrade, it is the right fit.

When DDD is the right call, use the domain-modeling skill to shape the internal structure (Entity vs Value Object, aggregate boundaries, domain events). CA decides where the layer lives; DDD decides what lives inside it.

Completion Rubric

Before Implementation

During Implementation

After Implementation

Before/After Pattern

When explaining layer violations or restructuring, always show both the problematic code (BEFORE) and the corrected code (AFTER). This makes the improvement concrete and reviewable.

Example: Controller with ORM Leak

BEFORE — controller directly uses ORM (Frameworks & Drivers leaking into Interface Adapters):

class OrdersController
  def show
    # BAD: ORM query directly in controller
    order = DB[:orders].where(id: params[:id]).join(:line_items, order_id: :id).all
    total = order.sum { |row| row[:price] * row[:quantity] }
    render json: { order: order, total: total }
  end
end

AFTER — controller depends on interface, ORM isolated in infrastructure:

# Use Case layer: defines the port (interface)
class OrderRepository
  def find_with_total(id) = raise NotImplementedError
end

# Infrastructure layer: implements the port
class SqlOrderRepository < OrderRepository
  def find_with_total(id)
    rows = DB[:orders].where(id: id).join(:line_items, order_id: :id).all
    Order.new(rows)  # maps to domain object
  end
end

# Interface Adapter layer: controller uses the port
class OrdersController
  def initialize(order_repo:)
    @order_repo = order_repo
  end

  def show
    order = @order_repo.find_with_total(params[:id])
    render json: OrderPresenter.new(order).as_json
  end
end

When demonstrating architectural improvements, the BEFORE block helps the user recognize their current situation, while the AFTER block shows the target. Without BEFORE, the guidance feels abstract.

Architecture Documentation

If docs/architecture.md doesn't exist, create it with:

# Architecture Overview

## Layer Structure
[Describe the four layers used in this project: Entities, Use Cases, Interface Adapters, Frameworks & Drivers]

## Directory Mapping
[Map directories to architectural layers]

## Dependency Guidelines
[Document dependency rules: all dependencies point inward, use interfaces at boundaries]

Converted and distributed by TomeVault — claim your Tome and manage your conversions.