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.

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.

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