name: architecture-paradigm-domain-driven\nrole: library\ndescription: Models a business in its own language. Use when the domain has real business rules to capture.\nalwaysApply: false\ncategory: architectural-pattern\ntags:
\nDesign for the future, build for now.
\nDDD is modeling a business in the business's own language. The goal is not\nto avoid structure. It is to avoid structure you cannot back out of, and to\ndefer structure you do not yet need.
\nUbiquitous language, bounded contexts, and a model built by talking to the\npeople who do the work. The measure of a domain model is whether a person\nin the business would recognize their own job in it.
\nClean Architecture. Mandatory layering. A mapper between every tier. A\ncount of design patterns applied before the first line of business logic is\nwritten.
\nThese are DDD-adjacent choices. Each has its own justification, and none of\nthem is entailed by DDD. Wanting to decouple an API from the domain is a\ngood reason to add a DTO. \"This is what DDD requires\" is not, because it\ndoes not.
\nThe building blocks are not the point, and this is not the repo's opinion.\nEvans said so himself, ten years after the book, about the book:
\n\n\n\"things like the entities and value objects [..] [People] come away\nthinking that that's really the core of DDD, whereas, in fact, it's\nreally not.\"
\n
\n\n\"I really think that the way I arranged the book gives people the wrong\nemphasis, so that's the biggest part of what I do is rearrange those\nthings.\"
\n
Source: SE-Radio Episode 226, \"Eric Evans on Domain-Driven Design at 10\nYears\" (video). Quotes as\ntranscribed by The Core of Domain-Driven\nDesign,\nwhich also cites his DDD Europe 2016 keynote criticizing the\n\"over-emphasis on building blocks.\"
\nWhat the core actually is: discovering subdomains and drawing bounded\ncontexts, in language the business already speaks. Entities, value objects,\nand aggregates are how a model reaches code once it exists. They are the\ntranslation, not the thing being translated.
\nRead the rest of this skill in that light. Every mechanism below is\noptional machinery serving a model you found by talking to people.
\nOnce a domain exists, create the data store and one concrete data object.\nPass that object from the repository into the business layer. At the start\nof a project, pass it out to the view as well.
\nThat is a legitimate starting state, not technical debt. One object moving\nthrough every layer is the cheapest thing that can work, and it is the\nshape the divergence protocol below is designed to split.
\nThe DTO arrives at the moment of divergence, not in anticipation of it.
\nTrigger: the view's response shape must hold for contract reasons while\nthe domain model needs to change.
\nMove: the old data object becomes the view DTO. The new domain object\ngains a translation into it. Where fields differ, a copy constructor maps\nthem, in either direction as needed.
\nThat is the whole mechanism. It works because the starting state (one\nshared object) is the same shape as the ending state's DTO, so the split\ncosts one rename and one translation function. This is why \"we might need a\nDTO later\" is not a reason to build one now: later is cheap.
\nOrdered by cost:
\nOption 3 carries a cost worth stating plainly: inheritance couples the\nlayers. Changing the base changes every context at once, which is the\nopposite of the flexibility the divergence protocol buys. It also feeds\nstraight into the boundary hazard below. Reach for it when duplication is\nthe larger present pain, and reach for it knowing what it trades away.
\nDo not reuse a data type across a network or other IO boundary without\nvalidating that you are not sharing something you should not.
\nThis is the one non-negotiable constraint in this skill. Everything else\nhere can be deferred, dropped, or added later. This cannot.
\nOption 3 is where it bites hardest: a field added to a shared base class\nappears silently in every serialized representation that inherits it,\nincluding the one crossing the wire. The convenience is real and so is the\nleak.
\nWhen two or more systems exchange commands over a network and do not\ndeploy atomically, a versioned request DTO lets you introduce a new shape\nwhile continuing to serve the old one, and migrate the systems one at a\ntime. Without it, any change to the command shape requires every system to\nupdate simultaneously, which fails the moment one update fails or one\nrelease waits on an app store, an IT department, or another team.
\nThat is a deployment constraint, not a DDD principle. Name it as such when\nyou justify the DTO, so the next reader knows which force put it there and\nwhen it can go.
\nNever in one pass. A refactor that tries to do every layer at once does not\nland. Per domain, in order:
\nThen repeat for the next domain. Keep the implementation simple until a\nneed for more appears.
\nceremony-audit lens in Skill(pensive:architecture-review). A mapper\nwhose fields are all 1:1 copies is a mapper with no job.These vocabulary items name the concrete tools and abstractions that show\nup when the paradigm is implemented. They are not required dependencies and\nthey are not part of the skill's tools: frontmatter (which is reserved\nfor Claude Code tool restrictions). Use this list to disambiguate during\narchitecture discussions.
ubiquitous-language-glossary: the term list the business and the code\nboth use, maintained as a first-class artifactcontext-map: names each bounded context and the relationships between\nthem, including where one term changes meaningcopy-constructor: the translation introduced at the moment of\ndivergence, mapping fields between a domain object and its view DTO