Learning path

New to Domain-Driven Design? Read the pages in this order: each step builds on the one before, and each page explains one idea with the same Order example.

An introduction, not a course

These pages explain each idea as far as you need it to use Alveolus. They are not a complete course on Domain-Driven Design. For the whole picture, read the books:

• Domain-Driven Design: Tackling Complexity in the Heart of Software, Eric Evans, 2003
• Implementing Domain-Driven Design, Vaughn Vernon, 2013
• Domain-Driven Design Distilled, Vaughn Vernon, 2016
• Learning Domain-Driven Design, Vlad Khononov, 2021

For

Developers who know TypeScript and have never used Domain-Driven Design

You need

TypeScript and classes, nothing about DDD

Order

The one of Domain-Driven Design Distilled (Vaughn Vernon, 2016): split the system first, then model each part

Already know DDD?

Go straight to Getting started and come back to a page when you need it.

Why DDD

Software gets hard to change when its code no longer says what the business means. DDD puts the business at the center of the code, in its own words.

1Building blocksWhat Alveolus gives you: the patterns of DDD as classes your code extends.

2The domainWhy the model of the business lives apart from frameworks and databases.

Split the system

Before writing a class, decide where its words apply. A "product" in the catalog and a "product" in ordering are not the same thing: each part of the system gets its own model.

3Strategic designWhat a bounded context is, and why contexts never share their models.

4Bounded contexts in the codeA context is a folder, with its layers inside.

Model the rules

Inside a context, the domain holds the business rules. Start from the smallest pieces and build up to the aggregate, the object that keeps the rules of an order.

5Value objectsValues such as an amount or an OrderId, checked once and never changed.

6EntitiesObjects that keep their identity while they change, such as an order line.

7AggregatesThe Order and its lines, changed as one unit through the root that keeps the rules.

8Domain errorsExpected failures, such as an empty order, named in the business's words.

9ResultHow a method returns a domain error instead of throwing it.

Record what happened

When the rules accept a change, the aggregate records it as a fact other code can react to.

10Domain eventsFacts named in the past tense, such as OrderPlaced.

Reach the outside world

The domain still needs things it does not own: a rule spread over several objects, a price from elsewhere, a place to store orders. It asks for them in its own words.

11Domain servicesRules that no single object owns.

12PortsWhat the domain needs from outside, as abstract classes.

13RepositoriesThe ports that load and save aggregates and views.

14ViewsThe read-only shape a query returns.

Run a use case

The application layer turns a request, such as "place this order", into a call to the domain, and saves the result.

15The applicationHow a request flows from the outside to the domain and back.

16Command handlersLoad an aggregate, call one method, save it.

17Query handlersRead a view, without loading an aggregate.

18Unit of WorkAll the writes of a use case kept together, or none.

Talk to other contexts

Contexts never import each other. They tell each other what happened in plain JSON, and each one translates what it reads into its own model.

19Event translatorsTurn domain events into messages for other contexts.

20Integration eventsVersioned JSON messages other contexts receive.

21Event publishersThe port that sends them to a broker.

22OutboxHow no message is lost when the change is saved.

23Published LanguageThe JSON contract between contexts.

24Open host servicesThe one entry point other contexts may call.

25Anti-corruption layersTranslate another context into your own words.

Keep it on track

Each idea above becomes a rule the checks verify, so the code keeps it whoever writes it.

26RulesWhat alveolus arch check reports, and why.

27Getting startedInstall Alveolus and run the checks on your project.

See also

• Getting started, to install Alveolus and run the checks
• Project layout, the folders and layers of a project
• Building blocks, every class @alveolus/core gives