Domain-driven design (DDD)

Commands represent a system’s [use cases]. These are the things that the system can do. Commands are typically implemented as classes or methods that encapsulate the logic for a particular operation.

The commands act on domain objects, which implement the business rules and data structures required to fulfill application operations.

In domain-driven software, the domain is modeled using [domain objects] and [domain events]. The domain objects are implemented using a variety of object-oriented design patterns, notably entities and value objects, and aggregates of both.

Domain objects are units of code that encapsulate business rules and data structures that are taken from the real-world business domain. For example, in a domain with users and teams, the software would probably have a User entity and a Team entity, and perhaps a JoinTeam service that would encapsulate the logic that encodes policies about which users are allowed to join which teams.

Entities are representations of things in the real world, such as users, teams, videos, and channels. Entities tend to persist after their destruction in memory, and the identity of each entity remains consistent throughout the lifetime of the system, even if instances of an entity are created and destroyed, and even it its attributes change. This is achieved by giving each entity a unique, immutable identifier. Thus, even if two objects have identical properties, they are considered to be different entities if they have different IDs.

Entities are mutable. Their attributes can be changed – except for their IDs. For example, a subscriber may change their email address, but it’s still the same subscriber because its ID does not change.

Ideally, the unique identifier for an entity type would be a business concept, such as a bank account number for bank account entities, or a customer number for customer entities. If no such permanent identifier exists in the real world, a unique identifier should be generated by the system. Technical identifiers are often used in practice, such as UUIDs or auto-incrementing integers.

Entities are typically generated at runtime from external input – end users, databases, etc. – and therefore entity classes should not assume that the data provided to construct them is valid. Therefore , entities will often have built-in runtime validation checking to ensure that all instances are always in a valid state. Modeling using these design constraints can help to enforce data integrity, not only of the application’s dynamic state, but also of the static data that is stored in persistence systems (eg. databases).

Not all domain objects need to be modeled as entities, because not all domain objects will need a unique identity or need to be persisted. If all we are interested in is the values or attributes of something, then value objects can be used.

Value objects are objects that represent a simple value in a domain model, such as a date or a price. A value object has attributes like an entity, but unlike an entity a value object does not have a conceptual identity. Two value objects with the same internal attributes are considered to be equal, and therefore value objects (unlike entities) cannot be considered to be unique.

As with entities, the values of value objects may be considered to be always "correct", since validation should be done at construction of the objects. But unlike entities, value objects should be modeled to be immutable. Thus, if you need to change a value object, you create a new one.

Entities may be [composed] from one or more value objects. For example, a subscriber may have a name, email address, and date of birth – all of which could be implemented as value objects. You could use the native types of the programming language to model these values, but by creating value objects you are explicitly stating that a value is an important part of the domain model. By comparison, implementation details such as the "last modified date" of an entity may not be considered important enough to be a value object. If the values are not relevant to the domain but are required only to implement the software, we may call these technical values.

Whether a piece of data should be modeled as an entity or a value object is not always a clear-cut decision. For example, an address could be modeled as either (value objects do not have to be restricted to a single value). In general, if something is important to the business it should be modeled as an entity. For example, in a real estate application, addresses may be important enough to be modeled as entities. However, if the address is just a way to contact a customer, it may be more appropriate to model it as a value object.

A complete domain model is made up of a mix of entities and value objects. Typically, you will end up with a lot more value objects than entities, but this will vary between domain models.

Some domain models may required that related entities and value objects (and perhaps other structures, too) be grouped together. This is where the aggregate pattern comes in. An aggregate is an object that encapsulates multiple related domain objects ([composition]). Each aggregate will have exactly one root entity, which provides a single point of entry to the whole group of objects. The root entity guarantees the consistency of changes made to all domain objects within the aggregate, and restricts external objects from holding references to its member objects.

An example of an aggregate would be a Customer entity that internally references lots of other entities and values objects that represent things like a PhoneNumber, PostalAddress, EmailAddress, and so on. From an external point of view, the Customer entity is a single unit of code, and all the other objects are hidden from view.

Like entities, aggregates have unique IDs.

Finally, [collections] may be used to group together multiple instances of the same domain object types, and [factories] may be used to encapsulate the initialization logic for any domain objects or domain collections.

Domain events are a way of representing things that happen in the domain. They are used to model things that happen in the real world, such as a customer placing an order, a product being shipped, or a payment being made.

Domain events are emitted by a component as a message that is somehow communicated with the rest of the application. Other components of an application may or may not handle the events when they receive them. Commonly, domain events will trigger additional domain events being generated by other components; for example, a domain event for a user being assigned to a department may trigger a domain event for the department’s payroll system to be updated. Other domain events may trigger processes such as invoicing, notifications, or inventory updates. Thus, complex business functionality is composed by having lots of independent services handle specific domain events.

Domain events are not emitted because of database changes. Rather, they are emitted before or during them, reflecting business decisions.

It is useful to distinguish between two categories of events:

Domain events are distinct from technical events, which are used to represent things that happen in the software itself, such as a user clicking a button, a database query being executed, or a message being sent over a network. Technical events are important; they often need to be logged and monitored. But they should not be part of the domain model.

Where business logic does not have an obvious home in any particular type of domain object, or if the logic is required to act on multiple domain objects, then a domain service may be used to encapsulate that logic. For example, consider the task of transferring money from one bank account to another. Putting such behavior in the entities for either the sending or receiving account feels misplaced. This is a business process that does not, conceptually, belong to any particular bank account. Moving this functionality to a separate service that acts upon both the entities for the sending and receiving account makes more logical sense, and it removes the need for circular dependencies between the entities.

Services are stateless (they do not have attributes of their own, so they have no internal state). They are used only to facilitate processes and tasks that act on domain objects. Domain services may also emit domain events.

Other types of services may exist in other (non-domain) layers of an application’s architecture. Infrastructure services may be used to interact with external systems such as message queues, and application services may prove beneficial to remove complex business logic from commands. For example, if a use case requires the orchestration of multiple tasks, this logic should be extracted to an application service, which becomes a dependency of the command that implements the use case.

While factories are responsible for creating new domain objects, repositories are responsible for fetching and persisting existing domain objects.

A [repository] is an abstraction of a persistent container or storage layer – usually a database system and any attached caching systems. The repository pattern acts as a mediator between the domain and the data mapping layer, providing an abstraction that allows handling the collection of entities as if it were a collection in memory. It enables operations such as searching, inserting, and deleting entities without exposing details of the persistence implementation.

The repository pattern hides the implementation details of the underlying persistence infrastructure from the high-level application code and domain logic, and also encapsulates things like security credentials and transaction management. The repository pattern gives the illusion of simple in-memory collections. Different repositories (for different types of domain objects) will have similar APIs, but internally they may use entirely different strategies for fetching and persisting objects.

Data wrappers ma be used to pull entity data from persistence, while identity maps may be used to cache entities in memory (so there can be only one instance of an entity in memory at a time).

Groups of related aggregates, entities, value objects, factories, repositories, and services may be packaged into modules. A module exposes a single interface through which other modules can interact with all the objects within it, simplifying the overall system design where there is a lot of complexity in the interactions between domain objects.

The outermost interface, presentation, or UI layer deals with input and output.

This layer is responsible for interpreting user input commands and presenting the system’s response to the client. This layer defines all the entry points to an application, and typically includes routing rules, view templates, UI controllers, and middleware.

The interface layer should not have any knowledge of business rules, use cases, persistence technologies, etc. It should only receive client input (eg. URL parameters) and pass these to the relevant commands or event handlers in the application layer.

The interface layer interacts with the lower application, services, or commands layer.

This layer defines everything that the application does as a series of commands, and message or event handlers. Overall, the application layer defines all of the [use cases] for the application.

The use cases will act on the domain objects and domain services in the domain layer below. The application layer should not do any processing directly, and it should not hold any state. Rather, the application layer is merely a thin [mediator] between the interface and domain layers. It is responsible only for delegating the processing of input to the appropriate domain objects or domain services, and for returning the output of those objects and services to the interface layer.

The domain or business layer is the foundation of domain-based architecture. It encapsulates domain objects, domain events, and domain services, which together model the business domain.

The command and event handlers in the application layer above tend to map to domain services in the domain layer, which in turn act on domain objects – aggregates, entities, and value objects.

The domain layer is the most important layer in a domain-based architecture.

Where domain objects and services need to fetch data and state from external systems – such as databases, local file systems, third-party web services, and also system software dependencies – access to these things should be provided via abstractions sitting in the infrastructure or framework layer.

This is the lowermost layer of the application architecture, and it’s the boundary to all the external systems on which the application depends. Objects here provide abstract interfaces to vendor libraries, system software, databases, email transport agents, message queues, and so on.

A common feature of this layer is the existence of the repository pattern, which is used to query and persist state stored in external systems such as databases.

The interface, application, domain, and infrastructure layers are the four main layers of a domain-based architecture. But additional layers may be added as required.

For example, it is not unusual for applications to require some amount of generic bootstrapping code, environment-specific configuration, and access to general-purpose utility functions. These sorts of concerns may be encapsulated in their own layers, and may be used by all other layers.

A key design constraint of domain-driven architecture is that each layer should only have knowledge of the layers below it in the hierarchy. Or, to explain it another way, software components within a layer should be accessed only by components in a layer above it. (Dependencies may skip layers. For example, components in the application layer may interact with both domain objects and abstractions of the infrastructure. For example, an application service for sending a user an email message may have dependencies on both a UserEntity domain object and an EmailTransportService.)

The domain layer should be isolated further by not having any direct dependencies on the infrastructure layer below it. This can be achieved by implementing inversion of control patterns at the boundary between the domain and infrastructure layers. [Interfaces] and [adapters] are commonly used for this purpose. The interfaces belong to the layer above (the domain layer), and the adapters to the layer below (the infrastructure layer). The interfaces define the dependencies required of the domain objects, domain events, and domain services. The adapters implement those interfaces. (And the responsibility for mapping interfaces to adapters may be delegated to a dependency injection container.)

Commonly, domain objects will interact with repository instances from the infrastructure later. Thus, the interfaces of repositories should belong to the domain layer, while the implementation of repositories belongs to the infrastructure layer. The domain therefore defines the methods and parameters that it accepts for repository access, but the implementation details of the persistence technologies are kept out of the domain layer.

The purpose of this design constraint is to enforce good [separation of concerns], which in turn promotes [loose coupling]. In particular, it is important that domain logic does not get scattered throughout a codebase – coupled to parts of the UI or database queries, for example.