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.
Commands: what someone asks for
Section titled “Commands: what someone asks for”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.
Events: what happened
Section titled “Events: what happened”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.
Private and public events
Section titled “Private and public events”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.
Read models: what people look at
Section titled “Read models: what people look at”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.
Putting the three together
Section titled “Putting the three together”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.
The words a model speaks in
Section titled “The words a model speaks in”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.