Skip to content

Commands, events and read models

Everything on an event model board is a command, an event or a read model. A command asks for something, an event records that it happened, and a read model shows the result.

This page uses the Acme Commerce shop’s basket to show how the three fit together.

A command is an intent. A shopper wants to put a mug in their basket, so the shop receives the command AddToBasket, with the product and the quantity the shopper chose. Commands are blue on the board.

Because a command is only a request, it can be refused. Before anything is recorded, the shop checks:

  • Rules on the values. A quantity must be a number. An email address must look like one.
  • Rules about the situation. AddToBasket is refused with the message That product is out of stock when the product cannot be bought. CheckOut is refused when the basket is empty.
  • Constraints. Some things must never happen twice, such as two customer accounts with the same email address. A constraint is how the model says so.
  • Permission. A policy says who may ask. See Screens and personas.

A refused command leaves no trace in the history. Nothing happened, so there is nothing to record.

accepted refused COMMAND AddToBasket EVENT BasketLineAdded READ MODEL BasketContents REFUSED That product is out of stock nothing recorded
A command is a request. Accepted, it leaves a fact behind; refused, it leaves nothing.

An event is a fact. Once the shop accepts AddToBasket, it records BasketLineAdded: this product, this quantity, this price, in this basket. Events are orange on the board.

Events follow three habits:

  • They are in the past tense. Basket line added, not Add basket line. The name says what was true, not what someone wanted.
  • They are never changed or taken back. If the shopper changes their mind, the model records a new fact, such as BasketLineRemoved, and leaves the old one where it is.
  • They carry what is needed and nothing else. Each event says one thing. When two different things can happen, they are two events.

Taken together, the events of a system are its memory. Everything the system knows is something that happened, in order. That is why you can ask later how did we get here? and get a real answer.

Most events are private: they are the business of one area of the shop. An event can be made public, which makes it a promise to the rest of the company. When checkout completes, the Storefront publishes OrderPlaced so that Sales can pick it up. See Automations and translations.

A read model is what someone sees afterwards: the basket page, an order list, a product catalog. Read models are green on the board.

A read model is not a store of its own. It is derived from events. A projection says how: when BasketLineAdded happens, add a line to BasketContents. When BasketLineRemoved happens, take it away.

This has two consequences worth knowing:

  • A read model is never the source of truth. The events are. If a read model looks wrong, the fix is to change how it is built, and Studio can rebuild it from the events.
  • You can have as many read models as you need. The basket page, a count in the top bar and a checkout summary can all be built from the same events, each shaped for what it is shown on.

A query is how a screen asks a read model a question, such as the basket with this id or products in this category.

Read a slice from top to bottom and you see the whole loop: someone asks, something happens, someone sees the result.

The shopper enters an address, the shop records that the address was entered, and the checkout page shows the progress so far. A slice is exactly one such loop.

Two more ideas keep the loop honest, and both belong to a whole domain rather than to a single slice:

  • Concepts are the typed values the business talks about: a quantity, an order number, an email address. A concept can carry its own rules, so the rule is written once and holds everywhere the value appears. A concept can also be marked as personal information.
  • Constraints are the things that must never happen twice.

Both have their own canvases in a domain. See Discover your domain.