The five building blocks
Event, Command, Read Model, Screen, and Automation, with a naming rule for each.
After this page, you can:
- name the five building blocks and say what each one is
- write a good name for an Event and for a Command
- tell an Event from a Read Model with a short test
Event: a fact that already happened
An Event is a business fact. Its name uses the past tense and the words of the business. Use two to four words. Examples: Appointment Added, Payment Authorized, and Pet Added.
Five rules describe an Event:
- An Event exists only when its Command worked.
- An Event does not change. A correction is a new Event, for example Order Total Corrected.
- An Event holds facts that the system captured. It does not hold a value that changes when other data changes, such as a running total.
- An Event belongs to one thing, such as one order or one pet.
- Start with the identity of that thing and one or two key facts. Add more later.
Some names look like Events and are not. The table shows the common mistakes.
| Mistake | Example | What to do |
|---|---|---|
| A user interface state | Sidebar Opened, Button Clicked | Leave it out, unless the business cares. |
| A technical step | Api Called, Response Received | Find the business fact below it. |
| A command name | Place Order | Use the past tense: Order Placed. |
| A generic change | User Updated, Record Deleted | Name the specific fact. |
| A calculation | Inventory Level Recalculated | Use a Read Model. |
Command: an intent to make something happen
A Command says what a role wants to do. Its name is a short order in business words: Place Order, Cancel Subscription, or Add Appointment. A name such as Load Orders is not a Command. It asks a question, so a Read Model answers it.
A Command can fail. Two kinds of failure exist, and the model treats them in different ways:
- The system refuses the Command because a rule does not hold. Nothing happened, so the system records no Event. You write the refusal as a scenario.
- The business tracks the failure as a fact, for example a declined payment. You record an Event, such as Payment Failed.
Each Command has one issuer. The issuer is one Screen or one Automation. The issuer acts for one named role, such as Clinic Staff. The word "User" is too generic.
A Command checks its own rules against earlier facts about the same thing. It does not read a Read Model to decide.
Read Model: an answer to one question
A Read Model is an answer that the system builds from Events. It has a clear question, for example: which appointments are on the calendar?
No question, no Read Model.
- Events are the only source. The same Events always give the same answer.
- You can rebuild a Read Model at any time. Building it has no side effects.
- A Read Model does not decide whether a Command works.
- Its name is a noun phrase for the data, such as Calendar or Order Summary. Names such as Order Summary Projector describe the machinery, so avoid them.
A Read Model with many rows is list-shaped. A todo list for an Automation is always list-shaped.
Screen and Automation: who starts the work
A Screen shows what a person sees and acts on. Use the words that the person uses: Dashboard or Calendar. A Screen shows its content and its fields. A title alone is a placeholder.
A Screen is one decision. It starts at most one Command. If a page offers three actions, model three Screen states, one for each action.
When no person acts, the system acts. That step is an Automation. A reminder, a deadline, and a timer are Automations, not Screens.
An Automation does not react to Events directly. It keeps a todo list. The todo list is a Read Model. The pattern is:
Example: Customer Registered adds a row to the list Notifications to Send. The Automation reads each row and sends a Command. The Event Notification Sent removes the row. Page 3 shows more.
Event or Read Model? A short test
Many beginners model a calculation as an Event. Ask these questions in order. Stop at the first clear answer.
- Did an actor do something? Then it is an Event.
- Is it only a calculation, such as a sum, a count, or a balance? Then it is a Read Model.
- Is it fixed once it exists? Then it is an Event.
- Does it change when other data changes? Then it is a Read Model.
Classify each name. Answer in your head, then open the answer.
Account Balance
Answer
Read Model A balance is a sum of earlier facts. It changes with each deposit.
Payment Authorized
Answer
Event A person or system did something, and the fact is fixed.
Order Flagged for Manual Review
Answer
Event It is an independent fact that someone decided.
Every field needs a source
Commands, Events, Read Models, and Screens carry fields. Each field must have a known source. A field with no source is a gap. Do not fill a gap with a guess. Find the missing data, or ask a person who knows the business.
This table shows where a Command field can come from:
| Origin | Example |
|---|---|
| A person types or picks it. | The bike that the customer picks. |
| The signed-in session. | The customer ID of the person who signed in. |
| An earlier Event. | The station from the Event Bike Reserved. |
| The system makes it. | A new ID, or the current time. |
| A message from outside. | The transaction reference from a payment provider. |
The system makes some values and people supply others. Mark a value that the system makes as generated. A value that a person supplies is not generated.
Every input of a Command must reach an Event, or you must explain why not. Data must not vanish between steps.
Check yourself
Label each name as Command, Event, Read Model, or not a business step: Cancel Subscription, Subscription Canceled, Subscription Count, Button Clicked.
Answer
Command, Event, Read Model, and not a business step. The user interface produces the last one.
A Screen has two buttons, Approve and Reject. Each button sends a different Command. What is wrong?
Answer
A Screen is one decision. Split it into two Screen states, one for each action, so it is clear which choice a person makes.
The Event Order Created holds the field total tax. Why is this a problem?
Answer
Tax is a calculation, and it can change. Keep the items and amounts in the Event. Calculate the tax in a Read Model.
A Command checks whether a seat is free by reading the Seats Read Model. What is wrong?
Answer
A Command checks facts about its own thing. It must not read a Read Model. Use the earlier Events about that seat.
Remember:
- Events are facts in the past tense. Commands are intents. Read Models are answers to one question.
- A Screen is one decision. A Command has one issuer.
- A calculation is a Read Model, not an Event.
- Every field needs a source.