clean-ddd-hexagonal

Clean Architecture, DDD, and Hexagonal Architecture

Use these related patterns to solve a concrete domain or dependency problem. This is an opinionated synthesis, not a mandatory folder layout. The user's explicit instructions take precedence over this skill's guidelines.

Choose the scope

Start from the requested behavior, existing domain model, and current dependencies. Preserve the project's language and architecture unless changing them is part of the task. Simple CRUD can remain simple; team size, entity count, and file length do not determine whether DDD is appropriate.

Design question	Relevant pattern
What language and consistency rules describe the business?	DDD, bounded contexts, aggregates
Which way should source dependencies point?	Clean/Onion Architecture
How can the application use different interfaces or infrastructure?	Hexagonal ports and adapters
Do reads and writes need different models?	CQRS
Must state be reconstructed from an event history?	Event Sourcing

If a business invariant is unknown, identify the specific missing rule and continue work that does not depend on it. Do not invent business behavior or require a discovery workshop for a local fix.

Preserve the boundaries that matter

• Keep domain behavior independent of HTTP, persistence, and messaging implementations. Put orchestration in application use cases and external I/O in adapters.
• Model entity identity separately from value-object equality. Choose aggregate boundaries from transactional invariants and contention.
• Prefer transactions contained within an aggregate. When a requirement needs cross-aggregate atomicity, make that tradeoff explicit rather than silently replacing it with eventual consistency.
• Use an outbox when a committed database change and external event delivery must be reliable together.
• Treat CQRS, Event Sourcing, repository interfaces, and separate presentation folders as choices justified by the task. Adapt example naming and directories to the project.

Deliver the requested model, patch, or review with affected boundaries and the tradeoffs that explain them. Validate changed invariants and adapter contracts at the appropriate level; an architecture question does not require implementing every pattern.

References

Load the reference for the decision being made, not the whole collection.

Task	Reference
Layer placement, dependency direction, composition root	LAYERS.md
Bounded contexts, ubiquitous language, context mapping	DDD-STRATEGIC.md
Entities, value objects, aggregates, repositories	DDD-TACTICAL.md
Ports, driver/driven adapters, alternative layouts	HEXAGONAL.md
CQRS, events, outbox, sagas, Event Sourcing	CQRS-EVENTS.md
Domain, integration, or architecture test design	TESTING.md
Compact pattern and placement lookup	CHEATSHEET.md

Primary foundations: DDD, Hexagonal Architecture, and Clean Architecture.