System Atlas
the atlas

Key terms in domain-driven design

A shared language and a toolkit of patterns for modeling complex business domains.

the gist

Domain-Driven Design tackles complex software by putting the business domain at the center. Strategically it uses a ubiquitous language and bounded contexts to align teams and carve the system into coherent models. Tactically it provides building blocks — entities, value objects, aggregates with roots, repositories, and domain events — to structure the model in code.

ANALOGY // DDD is like writing a company's operating manual: first everyone agrees on precise terms (ubiquitous language), then you divide the manual into departments where each term is defined once (bounded contexts), and each department is built from standard forms and procedures (the tactical patterns).
living diagram01 / 06
Strategic terms on top set the frame; tactical building blocks below structure the model.
01
Ubiquitous Language
shared team vocabulary
02
Bounded Context
where a model stays consistent
03
Entity vs Value Object
identity vs attributes
04
Aggregate + Root
consistency boundary
05
Repository
collection-like persistence
06
Domain Event
record of what happened
01

Ubiquitous language

DDD starts by insisting that developers and domain experts speak one shared, precise vocabulary — and that the same words appear directly in the code. If the business says 'policy' and 'premium,' the classes are named Policy and Premium, not GenericRecord and Amount. This kills the costly translation layer between how the business thinks and how the software is built, and it is the foundation everything else rests on.

02

Bounded context

In a large system the same word means different things in different areas — a 'customer' in billing is not the 'customer' in support. A bounded context draws an explicit boundary within which the model and its terms have exactly one meaning. Splitting the domain into bounded contexts, and mapping how they relate, is the core strategic move that keeps a big model from collapsing into ambiguity.

03

Entity vs value object

Two of the tactical building blocks describe objects. An entity has a distinct identity that persists over time — a User is the same user even if their name and email change. A value object has no identity and is defined solely by its attributes — a Money of $5 or a Color are interchangeable with any other with the same values, and are treated as immutable. Deciding which an object is clarifies how you compare, store, and mutate it.

04

Aggregate and aggregate root

An aggregate is a cluster of related entities and value objects treated as a single unit for data changes, with one entity designated the aggregate root. Outside code may only reference the root, which enforces the aggregate's invariants and guards its internals — you don't reach in and edit a line item directly, you go through the Order. The aggregate is the boundary of transactional consistency, the thing you load and save as a whole.

05

Repository

A repository gives the illusion of an in-memory collection of aggregates, hiding how they are actually stored. Code asks the repository to add, remove, or find aggregates by identity, and the repository translates that into database queries behind the scenes. This keeps persistence details out of the domain model, so the business logic reads as if the database didn't exist.

06

Domain event

A domain event is an immutable record that something meaningful happened in the domain — OrderPlaced, PaymentReceived — named in the past tense and in the ubiquitous language. Events let one part of the system react to another without tight coupling, and they are the natural seam between bounded contexts and toward event-driven and event-sourced designs. Together these patterns are the 'tactical' half of DDD, sitting beneath the strategic language and contexts.

the full picture
01

What DDD is and why it exists

Domain-Driven Design (DDD), introduced by Eric Evans in 2003, is an approach to building software for complex business domains. Its central claim is simple but demanding: the hardest part of most serious software is not the technology, it's understanding the business problem deeply and translating that understanding faithfully into code. So DDD puts the domain — the business's concepts, rules, and processes — at the very center of design, and organizes both the team's collaboration and the code's structure around a rich model of it.

DDD is best understood as two halves. Strategic DDD is about the big picture: aligning the team's language and carving the whole system into well-bounded pieces. Tactical DDD is about the building blocks: the concrete patterns you use to express the model in code. You can adopt the strategic ideas without every tactical pattern, and the strategic side is where most of the lasting value lives. The terms below are the vocabulary you'll hear in any DDD discussion.

02

Ubiquitous language and bounded contexts (strategic)

The ubiquitous language is the heart of DDD. It is a single, rigorous vocabulary, developed jointly by developers and domain experts, that is used *everywhere* — in conversations, documentation, and directly in the code's class and method names. The goal is to eliminate the lossy translation that normally sits between how the business describes its work and how programmers model it. When the domain expert says "a claim is adjudicated," there is a Claim with an adjudicate() method, not an UpdateRecord call on a DataProcessor. Ambiguity in the language is treated as a bug in the model.

But one language cannot stay consistent across a large enterprise: "customer," "product," or "account" genuinely mean different things to billing, shipping, and support. A bounded context is DDD's answer — an explicit boundary within which a particular model and its ubiquitous language are unified and consistent. Inside the context, every term has one meaning; across contexts, the same word may map to different models. Dividing a domain into bounded contexts, and drawing a context map of how they integrate, is the key strategic act, and it is why DDD aligns so naturally with microservices: a bounded context is a strong candidate for a service boundary.

03

Entities and value objects (tactical)

Within a bounded context, tactical patterns give the model its shape, and the most basic distinction is between two kinds of object.

  • An entity is defined by a continuous identity rather than its attributes. A User, an Order, an Account remains the same conceptual thing throughout its life even as its data changes — a user is still that user after they change their name, email, and address. Entities have a unique identifier and a lifecycle, and you care about *which* one you're holding.
  • A value object has *no* identity; it is defined entirely by its attributes and two instances with the same attributes are considered equal and interchangeable. Money(5, "USD"), a DateRange, a Color, an Address are typical examples. Value objects are treated as immutable — you don't change a value object, you replace it with a new one — which makes them safe to share and easy to reason about.

Deciding whether a concept is an entity or a value object is one of the most clarifying modeling questions in DDD, because it dictates how you compare, store, and mutate it.

04

Aggregates, repositories, and domain events (tactical)

Real domains are graphs of related objects, and letting any code modify any object freely makes consistency impossible to guarantee. DDD's answer is the aggregate: a cluster of associated entities and value objects that is treated as a single unit for data changes. Each aggregate has one designated aggregate root — an entity that is the only member outside code is allowed to reference. All access and modification go through the root, which enforces the aggregate's invariants (business rules that must always hold) and guards its internals. An Order aggregate, for instance, owns its LineItems; you never edit a line item directly, you tell the order, and it keeps the total consistent. The aggregate is also the natural transactional consistency boundary — the unit you load and save atomically.

Two more patterns round this out. A repository provides a collection-like interface for retrieving and persisting aggregates (by their root's identity), hiding the actual database behind an abstraction so the domain model stays free of storage concerns — one repository per aggregate root is the usual rule. A domain event is an immutable record that something meaningful happened, named in the past tense in the ubiquitous language: OrderPlaced, PaymentReceived, InventoryDepleted. Domain events let parts of the system react to each other without tight coupling and are the bridge to event-driven and event-sourced architectures, as well as a clean way for one bounded context to notify another.

05

When to use DDD — and when not to

DDD is powerful but heavy, and its patterns are a cost as well as a benefit. The strategic ideas — ubiquitous language and bounded contexts — are cheap, broadly applicable, and improve almost any non-trivial project, because clear language and clear boundaries help regardless of scale. The tactical patterns — aggregates, repositories, domain events, and the modeling rigor around them — pay off when the domain is genuinely complex: rich business rules, many interacting concepts, logic that will evolve for years. That is exactly the setting Evans wrote for.

Where DDD does *not* fit is simple, data-centric software — a basic CRUD app, a reporting tool, a thin API over a database. There the domain "logic" is trivial, and layering entities, value objects, aggregates, and repositories over it produces ceremony with no payoff. Applied blindly, DDD becomes over-engineering. Used well, it pairs beautifully with clean architecture — DDD supplies the model that lives at the center (entities and use cases), and clean architecture supplies the structural rules that keep that model insulated from frameworks and databases. The two together give you software whose code reads like the business it serves, which is the entire point.

what to remember
01

Ubiquitous language: one shared vocabulary used identically by developers and domain experts, in speech and in code.

02

Bounded context: an explicit boundary within which a model and its terms have a single, consistent meaning.

03

Entity: an object defined by a persistent identity that stays the same even as its attributes change.

04

Value object: an immutable object defined only by its attributes, with no identity of its own.

05

Aggregate + aggregate root: a cluster of objects treated as one consistency unit, accessed only through its root.

06

Repository provides collection-like access to aggregates; a domain event records something meaningful that happened.

check yourself

Quick quiz

Q1

What distinguishes an entity from a value object in DDD?

Q2

Why must outside code go through the aggregate root rather than modifying inner objects directly?

follow the thread