Explained with a diagram · Software design
DDD architecture: the layers of domain-driven design, with a diagram
In short
DDD architecture is the way a system built with domain-driven design is organised: the business logic lives in a domain model that is isolated from user interface, application and infrastructure code. In its layered form there are four layers (user interface, application, domain and infrastructure), and the domain layer does not depend on any of the others. At a larger scale the system is divided into bounded contexts, each with its own model and ubiquitous language. The approach comes from Eric Evans's 2003 book Domain-Driven Design.
Updated · by the ChartCraft team · one of the patterns and models explained with a diagram
What does a DDD architecture look like as a diagram?
The diagram is a stack of four layers. Requests enter through the user interface layer, the application layer coordinates the use case, the domain layer makes the business decision, and the infrastructure layer supplies persistence and messaging. The domain layer declares what it needs, such as a repository interface, and the infrastructure layer implements it, so the domain depends on no other layer.
Mermaid code for this diagram
flowchart TD
subgraph ui["User interface layer"]
controller["Web UI and API controllers"]
end
subgraph application["Application layer"]
appService["Application service (Place order use case)"]
end
subgraph domain["Domain layer"]
aggregate["Order aggregate (entities and value objects)"]
repoInterface["OrderRepository interface"]
domainEvent["Domain event (OrderPlaced)"]
end
subgraph infrastructure["Infrastructure layer"]
repoImpl["OrderRepository implementation (ORM)"]
publisher["Event publisher (broker adapter)"]
database[("Database")]
end
controller -->|"calls"| appService
appService -->|"delegates decisions to"| aggregate
appService -->|"loads and saves through"| repoInterface
aggregate -->|"raises"| domainEvent
repoInterface -.->|"implemented by"| repoImpl
domainEvent -.->|"published by"| publisher
repoImpl -->|"reads and writes"| database
Paste it into any Mermaid renderer, or check and export it with the Mermaid syntax checker and Mermaid to PNG.
What are the layers and parts of a DDD architecture?
The layers are user interface, application, domain and infrastructure. The domain layer holds the model: aggregates made of entities and value objects, domain events and the repository interfaces. The other layers exist to keep that model free of technical concerns.
| Part of the diagram | What it is | What it does |
|---|---|---|
| Web UI and API controllers | User interface layer | Shows information and turns user or API requests into calls to the application layer. Domain entities are not sent to the screen directly; they are translated into view models. |
| Application service (Place order use case) | Application layer | Defines the jobs the software does and directs domain objects to do them. It is kept thin: it coordinates tasks and holds no business rules. |
| Order aggregate (entities and value objects) | Domain layer: a cluster of entities and value objects with one root | Enforces the invariants for the whole cluster. Outside objects may hold a reference to the root only. |
| Domain event (OrderPlaced) | Domain layer: a record that something happened that domain experts care about | Lets other parts of the system react to the change, often asynchronously. |
| OrderRepository interface | Domain layer: the contract for storing and finding aggregates | Gives query access to aggregates in the language of the domain, with no database details. |
| OrderRepository implementation (ORM) | Infrastructure layer | Implements the repository interface with a persistence technology such as an ORM. |
| Event publisher (broker adapter) | Infrastructure layer | Hands domain events to a message broker or other external system. |
| Database | Infrastructure layer | The persistent store. The domain model does not know which one it is. |
What are the building blocks of the domain layer?
Evans's pattern language gives the domain layer seven building blocks: entities, value objects, aggregates, domain events, services, repositories and factories. The diagram shows three of them for one use case.
| Building block | What it is |
|---|---|
| Entity | An object distinguished by its identity rather than its attributes, with a life cycle. |
| Value object | An object that matters only for its attributes and logic and has no conceptual identity. |
| Aggregate | A cluster of entities and value objects with a boundary and a single root entity; outside objects reference the root only. |
| Domain event | A record that something happened that domain experts care about. |
| Domain service | A significant process or transformation that is not a natural responsibility of an entity or value object, modelled as a standalone operation. |
| Repository | Query access to aggregates, expressed in the ubiquitous language. |
| Factory | An object that takes over the creation of complex objects and aggregates. |
The definitions on this page follow Eric Evans's Domain-Driven Design Reference (Domain Language, 2015), which is published under the CC BY 4.0 licence.
Which way do dependencies point in a DDD architecture?
Towards the domain. The domain model layer must not depend on any other layer. In Microsoft's reference design the application layer depends on the domain and infrastructure layers, and the infrastructure layer depends on the domain layer, because it implements the interfaces the domain declares.
Evans's original formulation is a plain layered architecture in which each layer depends only on the layers below it. What he calls the key goal is isolation of the domain model, and he notes that related patterns such as hexagonal architecture may serve as well or better, to the degree that they keep the domain model free of dependencies on other system concerns.
What is a bounded context in DDD architecture?
A bounded context is a boundary, typically a subsystem or the work of one team, within which a particular model is defined and applicable. A large system has several, because one model cannot serve every part of a business without becoming ambiguous.
| Strategic pattern | What it means |
|---|---|
| Bounded context | The explicit boundary inside which one model and one ubiquitous language apply. In a microservice system, each bounded context usually maps to a service. |
| Ubiquitous language | A language structured around the domain model and used by all team members within a bounded context, in conversation and in code. |
| Context map | A large-scale view of every model in play and how the contexts relate to each other. |
| Anticorruption layer | A translation layer a downstream context builds so that an upstream system's model does not leak into its own. |
| Core domain | The most valuable and specialised part of the model. Evans's advice is to make the core small and apply top talent to it. |
When should you use a DDD architecture?
Use it for software with a complex domain, where a lot of often-messy business logic has to be organised and will keep changing. For simple data-entry services it is more structure than the problem needs.
Use it when
- The business rules are complex and are the main reason the software exists.
- Domain experts are available to work on the model together with developers.
- The system is large enough that one shared model would be ambiguous, so it has to be split into contexts.
Skip it when
- The service is simple CRUD; a simpler, data-driven design is enough.
- There is no access to people who know the domain.
- The difficulty is technical (scale, latency, integration) rather than in the business logic.
What are common mistakes in a DDD architecture?
The usual failure is that the layers exist on paper while business logic and technology remain mixed together.
- Business rules in application services or controllers. The application layer only coordinates; decisions belong to aggregates and domain services.
- Domain classes that depend on the framework. Entities should not inherit from, or reference, ORM or other infrastructure types.
- One model for the whole company. Multiple models are always in play on a large project; make the bounded contexts explicit instead.
- Reaching inside an aggregate. Changing an inner entity without going through the root bypasses the invariants the aggregate protects.
- Sending domain entities straight to the UI. Translate them into view models at the boundary.
- Applying every pattern to every service. The patterns matter less than keeping the code aligned with the business problem and its language.
How do you draw a DDD architecture diagram?
Draw the four layers as stacked groups, place the building blocks of one use case inside them, and add arrows for who calls or implements what. Check that nothing in the domain layer calls the infrastructure layer directly.
What do real domain model and architecture diagrams look like?
Live diagrams from the public ChartCraft gallery, each generated from a plain-English description. Open one to see the prompt that produced it.
Questions
What is DDD architecture?
DDD architecture is the structure of a system built with domain-driven design. Its defining feature is a domain model, the code that expresses the business rules, isolated in its own layer from user interface, application and infrastructure code, inside an explicitly bounded context.
What are the layers of a DDD architecture?
Four: the user interface layer, the application layer, the domain layer and the infrastructure layer. The application layer coordinates use cases, the domain layer holds the business rules, and the infrastructure layer provides persistence and other technical services.
What is a bounded context?
A bounded context is a boundary, typically a subsystem or the work of a particular team, within which a particular domain model is defined and applicable. Terms have one meaning inside it, and the same word may mean something else in another context.
Is DDD the same as microservices?
No. Domain-driven design is an approach to modelling and structuring software; microservices are a way of deploying it. They fit together because a bounded context is a natural boundary for a microservice, but DDD can be applied inside a single application too.
What is the difference between DDD and hexagonal architecture?
DDD is an approach to building a model of the domain and drawing its boundaries. Hexagonal architecture is a way of arranging code so that the model stays independent of technology. Evans notes that hexagonal architecture can serve the same isolation goal as his layered architecture, or serve it better.