clean-architecture · git:20260709.45dd358 · 2026-07-09 · sha256 5991a906daca04ba

clean-architecture git:20260709.45dd358A

Immutable. This exact content never changes and is served at /api/v1/blob/5991a906daca04ba.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_xvhhcbjglh7oresg/5991a906daca04ba1ab591419d3ff2dc38444f4cee03eed7b554fc074819cc41.json

Then /plugin install clean-architecture@markdownregistry-xvhhcbjglh7oresg in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: clean-architecture
description: >-
  Clean architecture layering with hexagonal (ports & adapters) boundaries —
  stack-agnostic. Use when designing or structuring a backend service or
  module, deciding which layer some logic belongs to, adding a new dependency
  between projects/modules, defining interfaces/ports for external
  capabilities, reviewing architecture, or answering "where does this go?" —
  in any backend language or framework. It encodes the four layers
  (Domain / Application / Infrastructure / Presentation), the inward
  dependency rule, and ports & adapters at the boundaries.
---

# Clean architecture (with hexagonal boundaries)

Stack-agnostic principles. The concrete realization — project layout, DI wiring, file placement — belongs to the stack skill (e.g. `backend-net`). **These rules get revised, not forced: if one fights the reality of a project, question the rule.**

## The four layers

| Layer | Owns | Never contains |
| --- | --- | --- |
| **Domain** | entities, aggregates, value objects, domain events, domain exceptions, validation rules | ORM/serializer/transport types, framework code, IO |
| **Application** | use cases — one service per use case; orchestration: build/validate domain objects, execute changes, raise events | presentation concerns, transport details, business rules that belong in Domain |
| **Infrastructure** | adapters that touch the outside: persistence, external clients, IO | business logic, use-case orchestration |
| **Presentation** | delivery mechanisms: HTTP endpoints, bus consumers, CLI — **thin**: validate/convert input → call an Application service → return/publish | business logic of any kind |

## The dependency rule

Source dependencies point **inward only**: Presentation → Application → Domain ← Infrastructure.

- Domain imports nothing from the other layers — ever.
- Application knows Domain. It must not know Presentation.
- Infrastructure implements what the inner layers define; nothing inward depends on its concrete types.
- Presentation knows Application (and the module's public contracts) — never another module's internals.

Concrete test: pick any file and read its imports. Every import should be from the same layer or an inner one. An outward import is the defect, wherever it appears.

## The hexagonal lens (ports & adapters)

Hexagonal architecture doesn't name layers — it splits the world into **inside** (your model and use cases) and **outside** (everything else), connected through **ports**:

- A **port** is an interface the inside defines for a capability it needs (a clock, a store, a notifier) or exposes (a use case).
- A **driving adapter** calls the inside: HTTP endpoint, bus consumer, CLI command, scheduled job — that's what the Presentation layer contains.
- A **driven adapter** implements a port for the outside: repository over a raw driver, external API client — that's what Infrastructure contains.

Define a port **only where the inside genuinely needs an outside capability** — not around every library reflexively. Frameworks the stack has deliberately committed to are accepted couplings; the stack skill names them.

## Clean vs hexagonal vs onion — one idea, three vocabularies

All three enforce the same dependency rule. Clean contributes the **layer vocabulary** used here; hexagonal contributes the **boundary mechanics** (ports/adapters); onion is the same picture drawn as rings. Don't debate the labels — enforce the rule.

## Where things go — quick answers

- Input validation of a request/message → Presentation (its validator), before anything else runs.
- A business rule/invariant → Domain (the aggregate or its validator).
- "When X happens, do Y and Z" orchestration → Application.
- Talking to anything with a connection string or URL → Infrastructure.
- Mapping between contracts (DTOs) and domain → the boundary that owns the contract (Presentation for transport contracts, Infrastructure for persistence shape).
- A new module's public surface → one entry point; internals stay private to the module.