After Event-Storming comes Event-Modeling - and then?

• Sun, Jul 20, 2025
• 7-minute read

Since longer, the idea behind Event-Sourcing and event-based applications clicked with me and it felt very natural. After reading Martin Dilger’s Book on Event-Sourcing and Event-Modeling and building a first application “the event-based way”, I was conviced that this will be my general approach for further projects.

This first application was pretty small in scope, contained only very few events, the laid out map was pretty easy to oversee and not much on this was changing during development. But now, together with a friend of mine, I’m thinkering about another application, slightly bigger - and it’s forseeable, that the much would be added, or existing stuff changed over time, once the application grows. Also building as a team brings in the requirement to have the map somewhere laid out, visible to discuss about it. And also to change it - but somehow keep track of the changes to the event-model which I understand as the (non-technical) architecture of the application.

This made me think about the process and tooling for mapping the whole application. And to be honest, just going the way of using Miro because everyone does that (and Martin Dilger recommends to use it), does not work for me. Stuff like not having a version-history to restore to earlier version (unless you pay for a subscription) just felt wrong.

So I went to see if there’s something else. And at first glance I was disenchanted and did not find what I was seeking.

After playing around with some Mermaid diagrams in some other context, the following idea grew in my head and I try so summarize it here:

The base idea

Wouldn’t it be cool if one could have single slices written down in separate files, with some Mermaid-like syntax to render a visual representation of what’s relevant for this slice. Having these files versioned would solve the versioning/history aspect. And with some magic tooling around, one could generate not just visual representations of the single slices, but from the overall application (if that’s needed).

What’s needed to build that?

I thougt about breaking this tooling down into separate areas and will explain those below:

• visual rendering (not having this makes the rest kind of useless)
• some structure + versioning (e.g. an idea how those files should be prepared and handled)
• the tooling around it all to generate a full overview of some kind

And if possible, the first part could/should be interchangeable if that makes sense (not yet sure about that).

Visual rendering of the Event Model

Coming with Mermaid on my mind, I first looked up how it’s possible to generate/render images from mermaid syntax, and for that there’s mermaid-cli available - untested, but looks like the way to go.

Unfortunately, Mermaid does not support rendering Event Models out of the box, but schicks has already proposed Event Modeling Diagram #5860 and I hope it will land in Mermaid sooner or later. As far as I see, lgazo is already working on a pull-request to implement this feature into Mermaid.

Since this is not yet ready and useable, I extended my search and came up with an Add-On for PlantUML. I shortly looked at it, but kind of disliked both PlantUML and the resulting visual representation. I know, that could be solved/improved. But I just gave up on that for now.

Structure to store the Event Model

Regarding the files, I thought about splitting things into separate files to keep them small and easy to handle - especially for later on once the need arises to perform changes to them - or even get someone to review a proposed change to the architecture.

So my rough idea would be like:

.event-model/
├── slices/
│   ├── userRegistration/
│   │   └── 01-userRegistration.txt
│   └── storageInventoryRun/
│       ├── 01-inventoryTrigger.txt
│       └── 02-inventoryFeedbackCollection.txt

I tend to collect everything that belongs to a Slice within a directory. Therein could be one or multiple files (numbered to order it in the resulting visual representation). And those files then contain the needed details for this slice.

For example, the userRegistration-Slice could look like this:

command: registerUser(firstName, lastName, email, password)
event: userRegistered(firstName, lastName, email, password)
view: userList

userRegistered -> updates userList

This could result in some colored boxes when rendered, simplified:

Regarding the syntax of the files I’m a bit unsure. There could be something pretty close to Mermaid syntax, but this would bind the tool to Mermaid for rendering. That’s a bit too closely bound. That’s why I came up with the above, simplified syntax that is far from being thought-through of course. But having something simple, it could be translated to Mermaid syntax for rendering - but also to PlantUML or whatever else’s syntax. This would make the rendering part replacable.

Another thought I had, was to go even further away from any “technical syntax” and use e.g. Markdown. What led me to this approach were the following two thoughts:

• parsing Markdown could be simpler because an existing parser could be used. (I heard everyone once needs to have written his own parser or compiler for something, that it’s hard - and I know I don’t want to go down that rabbit hole for now)
• having an even more human friendly representation of a slice’s content could make it easier to discuss and review changes within the project team

So the above example in Markdown could look like this for example:

# Story
This describes how a new user can register for the application.

# Commands
## registerUser
Needed:
- firstName
- lastName
- email
- password

Stored Events:
- registerUser

# Events
## registerUser
Needed:
- firstName
- lastName
- email
- password

Updates:
- userList

# Views
## userList
Needed:
- firstName
- lastName
- email

This could even include some human-readable context to describe this slice. Somewhat similar to a user story that explains, who can achieve what with this functionality.

It could be extended with validation rules (given-when-then rules) and so one. But I guess you got the point of the human readable format.

Tooling to work with the stored Event Model source files

One thing that struck me was the handling of things that are relevant to multiple slices.

In the userRegistration example above, there’s the list of Users. This list will be updated whenever a new user registers. But it could be needed as data-source in another slice, or even worse, be used to read and update also in a second slice. Let’s see an example with a second slice for updating the user’s name, this ready from the user list, then stores an event - and based on this, the userList will be updated:

Following the above directory-structure, the left and the right slice in this diagram would reside in different files. And both would probably mention the userList. This is fine, as it’s needed when reading that single slice’s definition. Also when rendering a visual representation of just one slice, those “shared” items must of course be visible.

But when rendering multiple Slices, or even a map of all slices, I think this visual duplication should be avoided as it clutters the overall map.

So my idea is to build a tooling around those plain-text files (of whatever syntax) and also perform some form or normalization. So that the userList is only shown once on the map, but with multiple arrows from/to it.

Conclusion

After collecting my thoughts and writing the above, my approach would be to go with

• markdown syntax in the files
• parsing out the needed bits and de-duplicating stuff
• throwing those into Mermaid to render graphics
  • rendering a graphic per slice
  • rendering an overall map with all slices
• (optional) render an architecture-document containing the descriptions (and their images) per single slice - and also the overall “big picture” of the whole map

Since the rendering via Mermaid is not yet possible, I’ll put this project aside for now. But I’m very curious for some feedback from folks more-seasoned with Event-Mapping as I am.