Skip to content

Explore the Acme Commerce sample

The quickest way to learn what an event model is, is to read a good one. Acme Commerce is a model of a mid-size online shop, and every example in this documentation comes from it. This page walks you through it in the order a newcomer would read it, and tells you what to notice.

Acme Commerce is one project with five applications, one for each area of the shop. They never share a database. They talk to each other only through a few public facts, such as a product being published. That is how real systems with several teams stay manageable.

Application Domain What it covers
Acme Catalog Catalog Products, the price list and the product lifecycle
Acme Shop Storefront Browsing, the basket, checkout and my orders
Acme Sales Sales Order intake, approval, confirmation and order status
Acme Purchasing Purchasing Suppliers, offers, replenishment and purchase orders
Acme Warehouse Warehouse Reservation, receiving, picking and dispatch

Six personas, the people the system is for, appear on its boards: Shopper, Merchandiser, SalesRep, SalesManager, Buyer and WarehouseClerk.

The project drawer with Acme Commerce expanded to show its five applications, Acme Shop opened to show its rows
Acme Commerce in the drawer: one project, five applications.

Start where a customer starts. In the drawer, open Acme Shop > Domains > Storefront > Event Models > Storefront.

  1. Stand back. The board opens zoomed out so you can see its shape. Each column is a slice: one behavior. Blue cards are commands, orange are events, green are read models.

    The Storefront board zoomed out: the Basket feature with several slices, each a column with a screen, a blue command, an orange event, and examples underneath
    The Storefront board zoomed out. The Basket feature is on the left; its slices run left to right.
  2. Zoom in on one slice. Zoom in on the first slice of the Basket feature, AddToBasket. Read it from the top down: first the screen the Shopper sees, then the command AddToBasket, then the event BasketLineAdded. A person asks, a fact is recorded.

    The first three slices of the Basket feature at full detail: AddToBasket, ChangeBasketQuantity and RemoveFromBasket, each with a Shopper screen, a blue command and an orange event
    AddToBasket, ChangeBasketQuantity and RemoveFromBasket. Notice the row labels on the left: who does it, and what kind of thing it is.
  3. Read across. Move right. ChangeBasketQuantity records BasketLineQuantityChanged, and RemoveFromBasket records BasketLineRemoved. Every event is in the past tense, because it is a fact.

  4. Find the view. Keep going to the BasketView slice. It has no command. It shows the read models BasketSize and BasketContents, built from the events to its left. Select the BasketContents card to open its editor.

    The editor of the BasketContents read model, with the events BasketLineAdded, BasketLineRemoved, BasketCleared and BasketLineQuantityChanged on the left, joined by lines to the properties of the read model on the right
    BasketContents is built from four events. The lines show which event property fills which read model property.
  5. Read the examples. Underneath each slice are its examples, each in the form given, when, then. Below AddToBasket you will find one where a listed product is added and BasketLineAdded follows, and one where the product is out of stock and the answer is That product is out of stock. These examples are how the model proves it does what it says.

Notice three things as you read. The names are the business’s own words, not technical ones. The events tell the whole story, so nothing is hidden. And a column never reaches into another’s data: a view only shows what the events to its left said.

The Storefront does not look inside Catalog’s data. When a product is published for sale, Catalog says so by publishing a public event. The Storefront receives that fact and translates it into its own words, so a change in Catalog’s vocabulary never leaks into the shop. Look for a slice of the Translator type in the Storefront’s browsing feature to see where this happens.

To see the whole picture at once, open Acme Shop > Context map. It draws how the application’s domains relate through the events they publish and consume. Compare it with the same map for Acme Sales.

Now open Acme Sales > Domains > Sales > Event Models > Sales. This board has people in more than one row: a SalesManager, a SalesRep and the System.

The Sales board zoomed out, with many slices in a row and their examples underneath
The Sales board at a glance.

Find the slice AutoApproveSmallOrders. It has a cogwheel where the others have screens. That is an automation: no person presses a button. The system reacts when an order is received, and approves it on its own.

The AutoApproveSmallOrders slice on the Sales board, with a cogwheel in the System row, the blue command AutoApproveSmallOrders and the slice RejectOrder beside it with a screen
An automation. The cogwheel stands for the system acting on its own.

Its first example reads A Small Order Approves Itself: given nothing, when OrderReceived, then OrderApproved, OrderConfirmationIssued, OrderConfirmed and OrderStatusChanged follow. Next to it, an example for RejectOrder says who is asking (Authenticated, as a SalesRep) and expects the command to be denied. Examples can say who may do what, too.

Two examples on the Sales board: A Small Order Approves Itself, with the event OrderReceived and the resulting events, and ARepCannotReject, expecting the RejectOrder command to be denied for a SalesRep
Examples are written in the same language as the model: given, when, then.

Models do not start as neat columns. Open Acme Shop > Domains > Storefront > Brainstormings > Acme big picture.

The Acme big picture brainstorming board: a cloud of orange event cards and sticky notes, with the events sorted into columns for Merchandising, Browsing and Ordering
The first column is the chaos storm: everything the team could think of. The columns beside it are what they sorted it into.

The first region is the chaos storm: every event the team could think of, in no order. The regions beside it are what they sorted it into: Merchandising, Browsing, Ordering. Sticky notes record the questions, risks, decisions and assumptions that came up along the way. In this sample, each note’s text begins with its kind, such as [DECISION] or [RISK]. A board like this is where an event model starts.

You cannot open Acme Commerce from another organization, but you can see everything above for yourself.

  • Build the same shape. Model your first behavior builds a small basket the way the Storefront does it: a state change slice with a screen, a command and an event, a view that counts what happened, and an example that checks it.
  • Read the sample’s source. The whole of Acme Commerce is written as Screenplay files in the public Cratis Screenplay repository, with a walkthrough that follows a product from the catalog to dispatch. You do not need a Studio account to read them. To see a Screenplay file drawn as a board, see Screenplay files.
  • Start from your own brainstorm. Brainstorm the way the Acme big picture board did, then turn the regions into slices.