Event model diagrams
Render an already-decided event model as a Mermaid eventmodeling diagram that
lives beside the code and is updated in the same change. If the event vocabulary
or the stream boundaries are not yet decided, model first; this skill draws a
chosen model, it does not choose one.
Source authority
Diagrams use Mermaid's native eventmodeling diagram type (Mermaid v11.15
and later). The grammar is owned by Mermaid, and
https://mermaid.js.org/syntax/eventmodeling.html is the authority whenever this
file and Mermaid disagree. Confirm the Mermaid version available to the renderer
before relying on a construct.
The Cratis artifacts a diagram refers to were originally checked against Cratis.Chronicle
18.3.0 and re-read against Chronicle 19.50.0 and the Arc query and command surface it is used with
(tool versions: cratis-screenplay-toolchain SKILL.md). The Mermaid claim above is
external and was not re-verified here.
What an event model is
It arranges a module's commands, events, read models, and automations on a left-to-right business-flow timeline, answering "what happens in this module, and in what order?".
One file per module or feature, alongside the code, with the diagram in a fenced
mermaid block. A system-overview file at the source root shows only
cross-module flows.
Grammar cheat sheet
Frame prefix: tf (timeframe — auto-connects to the previous frame) and
rf (resetframe — breaks the chain; start each independent flow with it). rf
replaces tf; tf N rf Name is invalid.
Frame: <prefix> <number> <type> <EntityName>. The number is unique;
declaration order does not matter because frames position by reference.
| Type | Swimlane | Represents |
|---|---|---|
ui |
UI / Automation | the persona interacting — a persona name, never a screen name |
pcr |
UI / Automation | a reactor or automation processor |
cmd |
Command / Read Model | a command |
rmo |
Command / Read Model | a read model |
evt |
Events | an event type, using the exact self-describing type name |
Multiple sources (->>). A read model or fan-in reactor fed by several
frames references them by frame number:
tf 10 rmo <ReadModelName> ->> 03 ->> 06 ->> 09
Namespaces. A Module. prefix creates a sub-swimlane. Use it for
cross-module entities and throughout the system overview.
Comments. %% -- Section --. A section header is a comment, never a frame.
Behavior type to pattern
%% -- State change: <CommandName> --------------------
rf 01 ui <Persona>
tf 02 cmd <CommandName>
tf 03 evt <EntityName><PastTenseVerb>
%% -- State view: <ReadModelName> (consumed by <Persona>) --
rf 04 rmo <ReadModelName> ->> 03
tf 05 ui <Persona>
%% -- Automation: <ReactorName> (reacts to our own event) --
rf 06 evt <EntityName><PastTenseVerb>
tf 07 pcr <ReactorName>
%% add the next two frames only when the automation invokes a command
tf 08 cmd <CommandName>
tf 09 evt <EntityName><PastTenseVerb>
%% -- Translation: <Outside>.<Fact> -> <Adapter> -> our event --
rf 10 evt <ExternalSource>.<FactName>
tf 11 pcr <AdapterName>
tf 12 evt <EntityName><PastTenseVerb>
- A state view's
rmoreferences the event frames it projects from by number; its consumeruiframe auto-chains after it. A passive read model has no consumer UI — emit only thermo ... ->>line with a%% passivecomment. - One definition of Translation everywhere: data from outside our own facts
becomes our own facts. Its flow starts at an outside-origin
evt(an<ExternalSource>.prefix marks it), passes through the adapterpcr, and ends at an event we own. Apcrthat reacts to our own event is an automation, whether it causes an external side effect, appends a follow-up event, or invokes a command (then draw thecmdand its resultingevtafter thepcr). Classify by where the data comes from, not by how the reactor is built. - Several consumers of one read model: declare each consumer
uias its ownrfframe with an explicit->>back to thermo.
Connections read forward
A diagram reads left to right, so every connection goes to a later frame, never back to an earlier one. In practice:
- Number frames in story order and put elements that belong together next to each other: a
persona and the command it issues, a command and the events it produces, an event and the
read model that projects it. A read model's
->>sources are frames that come before it. - When a later event must change what an earlier read model shows, do not draw an arrow back to
that read model. Draw a new
rmoframe after the later event, sourced from the events that now matter (it is the same read model carried to a later state), and give it its own consumeruiframe if a person looks at it. The earlier frame stays as it was: it correctly showed that earlier point in the story. The model itself is unchanged; its projection simply consumes the later event. - If the natural place for a frame is already taken, insert it just before or after rather than wiring across the gap.
Adapted from Martin Dilger and Nebulit GmbH's core rules (references/provenance.md); their
board mechanics (columns, cells, linked copies) do not apply to Mermaid frames.
The command rules table
Mermaid's eventmodeling grammar has no shape for validation or guards. After the
diagram, add a ## Command rules section: a table with Command, Rules,
and Emits / result, summarizing validator, value-invariant, provider,
concurrency, and authorization rules plus no-op and diff behavior, in human
language. Include commands that emit no event.
Process
- Discover the behaviors by scanning the module for the artifacts that
define them: command records for state changes, read models without a command
handler for state views,
IReactorimplementations that call out of the system or return events or commands in response to our own events for automations, and adapters that take outside data in as our own events for translations. Choose the authority here: when an accepted model covers the scope (or the repository is opted in, percratis-screenplay-modeling-lifecycle), read the behaviors from its slices (StateChange,StateView,Automation,Translate) and render from the model; otherwise the code is the authority. Report code that disagrees with the model as drift, separately; do not add unmodeled behavior to the diagram. Use the exact type names. - Order frames by domain causality — what must happen before what. Put state
views after the events they project from. Use
rfonly between independent flows, never between sibling events of one flow, or the diagram becomes a tall tower one event wide. - Write the diagram and the command-rules table.
- Verify it renders without a syntax-error banner, then reconcile it against
the authority chosen in step 1 (the model's slices, or the code's markers):
every behavior appears, classified by the type the authority gives it. A clean
render proves valid Mermaid, not completeness — close the gaps against the
authority, never from memory. List model/code drift in the report instead of
resolving it in the diagram. When the code is the authority, also find what changed since
the diagram was last updated: the last commit touching the diagram file is the baseline; list
the behavior commits in the module's folders since then
(
git log --reverse <baseline>..HEAD -- <module folders>), oldest first, and check each against the diagram. When an accepted model is the authority, report code that disagrees with it throughcratis-screenplay-render-and-gap-fill(hand-written changes), not in the diagram.
Common mistakes
- A command that emits several events chains them with consecutive
tf ... evt ...frames. Do not fight the auto-chain withrf. - The same event emitted from several commands gets its own
tf evtframe at each emit point. Do not merge them into one. - Several consumers of one read model — the first auto-chains; each
additional consumer needs an explicit
rf <n> ui <Persona> ->> <rmo-number>. - A screen name in the
uilane. Theuilane is the persona. - A section header written as a frame. Section headers are
%%comments. - A cross-module flow updated in one place. It needs three: the overview diagram, the source module's outputs, and the target module's inputs.
Verify
- The diagram renders with no syntax-error banner.
- Every behavior in the module appears, with the type its authority (the accepted
.playslice, otherwise the code) gives it; drift is reported separately. - Every event frame uses the exact event type name from the source.
- Independent flows start with
rf; sibling events within a flow do not. - Passive read models have no consumer
uiframe. - The command-rules table covers every command, including those that emit nothing.
- Cross-module flows are reflected in all three places.
Route near misses
- An accepted model covers the scope (or the repository is opted in): it is the source for this diagram; do not redraw from code and never change the model to match a diagram. The diagram is a view of it.
- Deciding the model rather than drawing one:
cratis-chronicle-event-modelingfor a hand-written Chronicle implementation, orcratis-screenplay-event-modelingwhen the model is authored as a Screenplay.playdocument.
Attribution for adapted method text: references/provenance.md.