# Event modeling

Event modeling lays a system out along time: commands on top, events in the middle, read models below. It is a design technique, and its diagrams are unusually good at showing where state actually comes from.

It suits event-driven systems, but the timeline layout helps even when the system is a plain database.

---

## When to reach for one

* Designing an event-driven system before the first line of code.
* Finding the read models nobody planned but everyone needs.
* Workshops, where the timeline gives everybody the same reference frame.

---

## How to draw it in Capable

| **Route**  | **Use when**                                                 |
| ---------- | ------------------------------------------------------------ |
| Excalidraw | Workshop mode; event modelling is a collaborative technique. |
| draw.io    | The tidied-up version afterwards, for the documentation.     |
| Mermaid    | A simplified timeline of the same model, for a page summary. |

---

## A worked example

The command and event sequence behind placing an order:

![Event modeling](https://help.gocapable.com/images/att1418002463.svg)

The source, which you can paste into a new diagram and edit:

```
sequenceDiagram
  actor Customer
  participant UI as Checkout UI
  participant Cmd as Order service
  participant Bus as Event store
  participant Read as Order history

  Customer->>UI: Place order
  UI->>Cmd: PlaceOrder command
  Cmd->>Bus: OrderPlaced event
  Bus-->>Read: project
  Customer->>Read: View order history
  Read-->>Customer: Order shown
```

---

## A few things that catch people out

* Events are facts in the past tense. OrderPlaced, not PlaceOrder.
* A read model with no event feeding it is a design gap, and the layout makes it obvious.
* Keep the swim lanes in the same order in every diagram or the technique loses its value.

---

## Related

[ArchiMate diagramEnterprise architecture views with the standard notation.](https://help.gocapable.com/diagrams/archimate-diagram.html)

[Block diagramBoxes and arrows, when that is genuinely all you need.](https://help.gocapable.com/diagrams/block-diagram.html)

[ExamplesWorking diagrams you can copy.](https://help.gocapable.com/diagrams/examples.html)

---

_Cheap to change means it stays true._