{% messageCard title="Article note" %}
This is the first article in the Pimp My App series. The series explores various aspects of modernizing a legacy project. Each post will dive into a different part of the transformation journey.
{% br /%}
This article focuses on gaining a deep understanding of the project’s domain using a technique called Event Storming.
{% /messageCard %}

## The Tale of Tired Codebase

It started like so many software projects do — with urgency. A few years ago, the company decided to launch its own e-commerce platform. There wasn’t much time to plan, research or architect. The business team needed something up and running — fast. The goal was clear: **start selling as soon as possible**.

A small dev team got to work. They got the initial version running in record time. It did just enough to satisfy early users and gained traction. But then came the first request: *“Can we just add this small feature?”* And then another: *“We need this to go live by the end of the week”*. And another: *“Marketing needs this new flow — it’s top priority”*.

There was no time to step back and think about architecture or domain design. No one documented the business logic — it lived in scattered conversations, Slack messages and the minds of a few burned-out developers. Code was copy-pasted, patched and layered on top of itself like sediment. The checkout flow alone had been reworked half a dozen times, with remnants of each version still lurking in the codebase.

Today, the system still runs — barely. Everyone knows it’s risky to touch. Developers onboard onto the project with a deep sigh. No one is quite sure how one module relates to another. Every change feels like surgery without a diagnosis. When a bug shows up in production, it’s anyone’s guess what caused it or how to fix it safely. And when a stakeholder says, “Can we just add one more thing?” the engineering team winces.

{% twitterPost id="1603711968971558914" /%}

So here we are: a product that grew fast, delivered value, and now stands as a monument to years of unspoken decisions. The team knows something has to change. But where do you even start when you don’t understand the system you’ve built?

## Introducing Event Storming

This is exactly the kind of situation where Event Storming proves valuable — not as a tool for immediate rewriting or refactoring, but as a way to take the first and most crucial step: **understanding the system**.

Event Storming is a collaborative workshop technique designed to uncover how a business process actually works. Instead of starting with code or technical architecture, it starts with business events — things that happen in the domain: `OrderCreated`,  `PromoCodeApplied`, `OrderShipped`, etc.

In a session, people from different roles — developers, product owners, domain experts, customer support — all get in the same room (or virtual whiteboard) and map out the flow of events that make up the system’s behavior. No diagrams, no UML, no formal structure. Just sticky notes and conversations.

The result? A shared understanding of how things really work — not how we think they work, or how they were supposed to work but what’s **actually happening today**.

## Types of Event Storming Sessions

Event Storming isn’t a one-size-fits-all technique — it comes in different forms depending on how deep you need to go and what kind of problems you’re trying to solve. Generally, there are three main levels of Event Storming:
### Big Picture Event Storming
This level focuses on mapping out an entire business domain at a high level. It’s great for identifying bounded contexts, aligning business and tech and spotting organizational bottlenecks. You’re not interested in every little detail — the goal is understanding how the system behaves as a whole.

### Process-Level *(a.k.a. Design-Level)* Event Storming
This is where you zoom in on a specific business process — like “placing an order” or “processing a payment”. The focus is on how things happen step by step, and how information flows between parts of the system. It’s incredibly useful for uncovering domain rules or finding inconsistencies.

### Software Design-Level Event Storming
The most granular level, where the goal is to go from domain knowledge to actual implementation details. This level often leads directly into designing aggregates, defining commands, shaping APIs and even laying groundwork for different patterns like Event Sourcing or CQRS.

{% hr /%}

For our e-commerce case — where we have a system that technically works but is full of unknowns — the most practical place to start is the Process-Level Event Storming. It strikes a balance between high-level clarity and actionable insight. It helps teams make sense of one critical process at a time, identify where the complexity lives, and gradually rebuild understanding from the inside out.

In the rest of this article, we’ll focus on Process-Level Event Storming — what it looks like, how to run a session, and why it’s such a powerful tool for untangling messy systems like ours.

## Main Concepts and Recommendations for a Successful Session

**1. Start with Domain Events**

Always begin by identifying the events that occur in the business process — things that happen and are meaningful to the domain, like "Order Placed," "Payment Confirmed," or "Inventory Reserved." These are the backbone of the session.

**2. Use the Ubiquitous Language**

Stick to the language of the domain — not tech jargon. Everyone should be able to understand the terms being used. If two people use different words for the same thing, talk about it and pick one.

**3. Visualize Everything**

Use sticky notes (physical or digital) with distinct colors for different concepts {% link href="#the-color-coded-language-of-event-storming" ariaLabel="Part two of article series" %} (more on that in the next section){% /link %}.

**4. Collaborate — No Spectators**

Everyone in the room contributes. Developers, designers, product owners, and domain experts should all participate. Silence or dominance from one group usually leads to blind spots.

**5. Embrace Imperfection**

The goal is discovery, not perfection. It’s okay to be wrong, to make guesses, or to leave sticky notes that say “?” or “needs clarification.” You’re surfacing unknowns — that’s part of the process.

**6. Work Left to Right, Chronologically**

Events should be placed in the order they happen. This helps build a timeline of the process and reveals cause-effect relationships.

**7. Highlight Hotspots and Confusion**

If something causes debate, confusion, or disagreement — mark it. These are the valuable parts. They often hide complexity, misunderstanding, or poor design.

**8. No Laptops, No Distractions (for in-person)**

Focused attention is critical. If remote, use a tool like Miro, MURAL, or FigJam — and ask everyone to stay engaged.

**9. Timebox, but Don’t Rush**

Give yourself enough time — especially for the first session. Event Storming can feel chaotic at first, but the insights snowball quickly. Don’t rush to “finish”; aim to learn.

## The Art of Curiosity

I want to highlight that **curiosity** is one of the most powerful tools you can bring to an Event Storming session. Rather than simply documenting what’s already known, the goal is to uncover gaps, challenge assumptions, and surface hidden complexity within the domain. Asking “why?”, “what happens next?”, or “who decides that?” can reveal critical insights that might otherwise go unnoticed. For example for every event, ask:
* *What caused this?* → Leads to a Command.
* *What happens next?* → Leads to more Events or Policies.

In the next chapter each building block is provided with example guiding questions.

## The Color-Coded Language of Event Storming

One of the most powerful aspects of Event Storming is its use of colored sticky notes to represent different elements in a system. Each color has a distinct meaning, and together they bring order to complexity by mapping out the flow of events, decisions, actions, and data across a business process. More than just visual flair, this color system makes cause and effect instantly clear — turning messy domains into collaborative, navigable models.

Here are the most common sticky note colors and what they represent:

### 🟠 Domain Event (Orange)
**What it is**: Something that happened in the domain and is meaningful to the business.

**Why it matters**: Domain events are the backbone of the process. They describe outcomes and help trace the system's behavior over time. They also provide a shared language between tech and business.

**Guiding question**: What happened?

![events](/assets/event-storming/events.png)

### 🔵 Command (Blue)
**What it is**: An instruction to do something — often triggered by a user or system.

**Why it matters**: Commands initiate change. They precede domain events and usually represent user intentions or system actions. Every command should ideally lead to one or more events — unless it’s rejected.

**Guiding question**: What triggered the event?

![commands](/assets/event-storming/commands.png)

### 🟡 Aggregate / Consistency Boundary (Yellow)
**What it is**: A cluster of domain objects that are treated as a single unit for consistency and transactional integrity.

**Why it matters**: Aggregates define where decisions are made. They are responsible for handling commands and enforcing invariants. In practice, this is where domain logic lives.

**Guiding question**: Who/what decided how to handle the command?

![aggregates](/assets/event-storming/aggregates.png)

### 🟣 Policy (Purple)
**What it is**: A rule, condition, or automated reaction that kicks off a command when certain events occur.

**Why it matters**: Policies help capture business logic and automation. They often live in the background and can be hidden inside code or processes. Making them explicit helps identify where complexity lives.

**Guiding question**: What automatically happens next?

![policies](/assets/event-storming/policies.png)

### 🩷 External System / Actor (Pink)
**What it is**: Any external service, system, or actor that interacts with your domain but isn’t controlled by it.

**Why it matters**: These notes clarify integration points. Identifying external dependencies early helps manage risks, delays, and error handling in the system.

**Guiding question**: What external systems interact with our domain?

![3rd party systems](/assets/event-storming/systems.png)

### 🟢 Read Model / View / UI (Green)
**What it is**: A projection or view of data meant for display — often read-only.

**Why it matters**: These notes represent the queries or views that users interact with. They help model what information needs to be available and when — especially important in systems using CQRS.

**Guiding question**: What information do users need to see?

![views](/assets/event-storming/views.png)

{% messageCard type="tip" title="Helpful Tip" %}
The screenshots above are provided solely to illustrate examples of color usage. They were intentionally designed to clearly show how different sticky note colors are used. In a real Event Storming session, while you should start with identifying a few Domain Events to get the conversation started, you should avoid focusing exclusively on one type of element. Instead, aim to move from left to right, following the flow of data and decisions through the system, and explore the broader context collaboratively as the model evolves.
{% /messageCard %}

## To put this all together

Event Storming is not just a modeling technique — it’s a collaborative discovery tool that helps teams untangle complexity, bridge communication gaps, and rediscover the true shape of their systems. At its core, Event Storming is about understanding how things happen in a domain by mapping out domain events, commands, policies, and external interactions using simple, color-coded sticky notes. What sets it apart is its ability to bring technical and non-technical people into the same conversation, using shared language and visual clarity to uncover how a system really works — not how it was imagined or documented.

### Strengths

One of its greatest strengths lies in its speed and low barrier to entry. Unlike formal modeling methods, Event Storming doesn’t require specialized tools or upfront structure. It embraces exploration over precision, allowing teams to quickly surface misunderstandings, design flaws, and hidden complexity. It’s especially powerful in legacy systems, where documentation is missing and institutional knowledge has eroded. As shown in example of our e-commerce app, Event Storming makes it possible to reconstruct and clarify even the most chaotic flows, step by step.

### Challenges

However, Event Storming isn’t without trade-offs. Its unstructured nature can be overwhelming at first, especially for teams unfamiliar with domain-driven design or those lacking facilitation experience. Sessions can easily go off-track without clear goals or a strong facilitator. Additionally, while Event Storming excels at discovery and communication, it doesn’t provide direct implementation guidance — it needs to be paired with technical design work to turn insights into architecture.

### Summary

When used intentionally, Event Storming becomes a lightweight but high-impact practice for teams struggling with unclear business logic, risky changes, or a lack of domain insight. It’s not about drawing pretty diagrams — it’s about creating shared understanding, fostering better decisions, and ultimately building better software.

Confused by your app’s domain? Learn how to break down processes, map events, and uncover what really drives your system in the process of Event Storming session.

Pimp My App - Event Storming

Idempotency is often overlooked in API design, yet crucial for reliability. Design and build asynchronous API that ensures robust performance and resilient operations.

#system-design

Pimp My App - Event Storming

Designing idempotent serverless systems