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.

DDD architecture diagram: user interface, application, domain and infrastructure layers, with the infrastructure implementing interfaces the domain declaresUser interface layerApplication layerDomain layerInfrastructure layerWeb UI and APIcontrollersApplication service(Place order use case)Order aggregate(entities and valueobjects)OrderRepositoryinterfaceDomain event(OrderPlaced)OrderRepositoryimplementation (ORM)Event publisher(broker adapter)Databasecallsdelegates decisions toloads and saves throughraisesimplemented bypublished byreads and writes
DDD layered architecture for one bounded context. Solid arrows are calls. Dashed arrows read is implemented by and is published by: the infrastructure classes depend on what the domain declares, never the reverse. Rendered by ChartCraft's layout engine.

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 diagramWhat it isWhat it does
Web UI and API controllersUser interface layerShows 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 layerDefines 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 rootEnforces 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 aboutLets other parts of the system react to the change, often asynchronously.
OrderRepository interfaceDomain layer: the contract for storing and finding aggregatesGives query access to aggregates in the language of the domain, with no database details.
OrderRepository implementation (ORM)Infrastructure layerImplements the repository interface with a persistence technology such as an ORM.
Event publisher (broker adapter)Infrastructure layerHands domain events to a message broker or other external system.
DatabaseInfrastructure layerThe 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 blockWhat it is
EntityAn object distinguished by its identity rather than its attributes, with a life cycle.
Value objectAn object that matters only for its attributes and logic and has no conceptual identity.
AggregateA cluster of entities and value objects with a boundary and a single root entity; outside objects reference the root only.
Domain eventA record that something happened that domain experts care about.
Domain serviceA significant process or transformation that is not a natural responsibility of an entity or value object, modelled as a standalone operation.
RepositoryQuery access to aggregates, expressed in the ubiquitous language.
FactoryAn 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 patternWhat it means
Bounded contextThe explicit boundary inside which one model and one ubiquitous language apply. In a microservice system, each bounded context usually maps to a service.
Ubiquitous languageA language structured around the domain model and used by all team members within a bounded context, in conversation and in code.
Context mapA large-scale view of every model in play and how the contexts relate to each other.
Anticorruption layerA translation layer a downstream context builds so that an upstream system's model does not leak into its own.
Core domainThe 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

Skip it when

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.

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.

Opens the studio with your text · or start from the Architecture diagram generator

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.

More patterns and models explained with a diagram

Describe the system in plain English and get the diagram.

Architecture diagram generator →