Most legacy systems don’t fail because of technology but because the team never understood the business correctly. This post walks through discovering a new domain with two workshop techniques, Event Storming and Domain Storytelling, and turning the results into module boundaries and code. Bounded contexts, context maps and aggregates are covered in the post on DDD and package structure; this post is the step before that.
1. Getting started: coffee, the first meeting and open questions
Key idea: before drawing anything, talk. Informal coffee first, then a meeting with domain experts and stakeholders within the first two weeks, where you listen more than you speak.
The architect has to build a shared understanding: information from different people often conflicts, and reading files someone else wrote doesn’t replace walking the process yourself.
In the first meeting (about 2 hours):
- Let others speak first, take as many notes as you can.
- Ask Why (why build this, why a SaaS model), then What (which problem, what goal, what alternatives), then How (how do we measure success, how big is the market, how is it solved without software). Open questions force people to think, unlike yes/no ones.
- 5 Whys: ask “why” five times in a row, each going one level deeper, to reach the root cause.
Afterwards, highlight the key facts in your notes. For the clinic case (a SaaS for private clinics in Europe), a few sentences already gave:
| Detail | Consequence |
|---|---|
| SaaS subscription for private clinics | Check healthcare regulation in each country you’ll sell to |
| Scheduling, treatment, prescriptions, medical records | Many areas; next step is finding the key process |
| 3 clinics interested, 2 considering | Real demand, not built on a hunch |
| 1,000–1,500 patients | Small scale |
2. Running the workshops
Key idea: fewer than 10 people, short blocks with breaks, start with the most critical process, and don’t juggle more than 3–5 processes at once.
- Who: decision-makers and domain experts. Experts can be developers: people maintaining a legacy system often know the processes deeply.
- How long: a first session of about 3.5 hours, in 30–60 minute blocks with 5-minute breaks, plus 15 minutes at the end to settle debates. People who don’t engage aren’t invited next time.
- Which process first: the domain’s most critical one: appointment scheduling (healthcare), claim assessment (insurance), order placement (retail), risk assessment (banking).
- As-is or to-be: model the current state (as-is) first, then the desired state with your software (to-be). To-be is a wish and will change.
3. Event Storming at Big Picture level
Key idea: everyone sticks business events on a long wall in time order, you clear out technical events, find pivotal events, then group them into highly cohesive groups.
Event Storming has three levels:
| Level | What you do |
|---|---|
| Big Picture | Sketch the whole process: events, order, groups, hot spots, external systems |
| Process | Go deep into each subprocess: actors, commands, policies, read models |
| Design | Design: aggregates, business rules, sometimes with pseudo-code |
Four kinds of notes at Big Picture level:
| Note | Usual colour | Meaning |
|---|---|---|
| Event | Orange | A business fact that already happened, past tense: “Appointment scheduled” |
| Hot spot | Red | An unanswered question or unresolved argument |
| External system | Pink | A system outside your control |
| Comment | Yellow | Extra notes and clarifications |
The steps:
- Warm up for 30 minutes with a familiar process (pizza delivery, bike rental).
- Stick one random event in the middle of the wall; people add earlier events to the left, later ones to the right. No idea is wrong. If an argument doesn’t resolve, add a hot spot and move on.
- Drop technical events: “Confirmation request sent to API”, “Invoice exported to PDF” are not business facts.
- Order by time: left to right (natural, fewer misses) or right to left (thinks differently, spots what was overlooked, but easier to miss events).
- Find pivotal events, draw boundaries, group into swim lanes, name each group.
flowchart LR
A[Appointment scheduled P] --> B[Treatment plan agreed P]
B --> C[Prescription given to patient P]
C --> D[Follow-up scheduled P]
D --> E[Treatment completed P]
E --> F[Records sent to national system P]
E --> G[Invoice sent to patient P]
Signs of a pivotal event (P):
- It’s a milestone in the process, or it starts a subprocess.
- Hard to reverse. Cancelling an appointment means telling the doctor, the patient, and releasing the room. A sent invoice can’t be edited; you issue a correcting invoice.
- Often a switch of actor: the front desk updates records, then the doctor reviews them.
4. Event Storming at Process level
Key idea: go deep into each group to find who acts (actor), what they do (command), which rule applies (policy), and what data they need to see to decide (read model).
| Note | Colour | Meaning | Clinic example |
|---|---|---|---|
| Actor | Yellow | A person or role interacting | Front desk, doctor, patient |
| Command | Blue | An action that changes state | “Schedule appointment” |
| Policy | Purple | A rule: when something must or must not happen | “No appointment if the patient has no insurance” |
| Read model | Green | Data needed to make a decision | The doctor’s free slots, list of free exam rooms |
Example, scheduling: the patient calls the front desk; the front desk confirms a date with a doctor, then with the patient; the front desk books an exam room; a policy blocks it without insurance. Starting treatment: the doctor drafts a plan from exam results and past records, the patient agrees, the doctor picks drugs; the policy “no contraindications for this patient” must pass before the prescription is handed over.
If you spot a duplicate process (scheduling a follow-up is almost scheduling an appointment, plus the policy “requires a prior appointment”), clarify it on the spot: reuse means less work.
From the wall to backend code the mapping is fairly direct (this is how I use it, not a hard rule):
| Note | In Spring/Java code |
|---|---|
| Command | An endpoint or application service method (scheduleAppointment(...)) |
| Event | A domain event; if pivotal and needed by other modules, an integration event via outbox/Kafka |
| Policy | A rule inside the aggregate (blocks a command) or a listener (event → new command) |
| Read model | A query/projection for a screen, maybe a view or a read table (CQRS) |
| External system | An adapter/anti-corruption layer (a translation layer between our model and theirs) |
| Hot spot | An open question to settle, often becomes an ADR or a ticket |
Example: the “no insurance, no appointment” policy as code
Two places for a policy, depending on whether it’s an invariant or a reaction to an event:
// Blocking rule: in the application service/aggregate, runs before the write
@Transactional
public AppointmentId schedule(ScheduleAppointment cmd) {
Patient p = patients.get(cmd.patientId());
if (!p.hasValidInsuranceOn(cmd.date())) {
throw new AppointmentRejected("NO_VALID_INSURANCE");
}
Appointment a = Appointment.schedule(cmd.patientId(), cmd.doctorId(), cmd.room(), cmd.date());
appointments.save(a); // AppointmentScheduled goes into the outbox table in the same transaction
return a.id();
}
// Reactive policy: "when treatment is completed, prepare the invoice" (in the Invoicing module)
@TransactionalEventListener // or a Kafka consumer if it's another deployment unit
void on(TreatmentCompleted e) {
invoicing.prepareDraftInvoice(e.treatmentId()); // idempotent by treatmentId
}
A blocking policy must run synchronously in the same transaction; a reactive policy runs after commit, so it must be idempotent (running it again gives the same result) because the event may arrive twice.
5. Domain Storytelling
Key idea: a practitioner tells the process as a story; you draw it with numbered actors, work objects and activities. Event Storming asks “what happened”, Domain Storytelling asks “who is doing what with what”.
Three building blocks:
- Actor: a person, a group or a system, named by role (“doctor”, not “Nam”).
- Work object: a noun being worked with: a phone call, an appointment, a prescription, an invoice.
- Activity: a verb, drawn as an arrow, linking actor and work object.
Each story is a sequence of numbered sentences. A coarse-grained, as-is example:
- The patient calls the front desk to ask for an appointment.
- The front desk schedules the appointment.
- The doctor examines the patient and starts treatment; the front desk schedules a follow-up.
- At the follow-up, the doctor reviews the results and completes the treatment.
- The front desk prepares the invoice and sends it to the patient.
There are three levels of detail: coarse-grained (overview), fine-grained (deep dive), or something in between. Error paths (“treatment doesn’t work, so adjust it and prescribe new drugs”) are not drawn on the overview; add an annotation and draw them as a separate story.
Group by three signals:
- Change of activity: scheduling is done, examination starts.
- Change of actor: the patient finishes treatment, the front desk starts invoicing.
- Change of a work object’s meaning: “product” means something else to a factory than to a software startup. That’s a strong bounded-context signal.
Preparing a Domain Storytelling session
- A quiet place; you must focus fully on the storyteller. Remote is often easier because nobody interrupts.
- A projector or continuous screen share, so the storyteller sees right away how they’re being understood and corrects it on the spot.
- Someone else drawing: listening, asking and drawing at the same time is very hard with several storytellers.
- Sometimes mix coarse and fine-grained in the first session, because an overview alone loses useful detail.
6. Which technique, and how to combine them
Key idea: you don’t have to pick one. Tell the story first so everyone understands the process, then Event Storm to find events, rules and boundaries.
7. From the wall to module boundaries
Key idea: the highly cohesive groups you found (Scheduling, Treatment, Prescriptions, Medical records, Invoicing) are candidate subdomains and bounded contexts; pivotal events are what flows across the boundaries between them.
flowchart LR
SCH[Scheduling] -->|Appointment scheduled| TR[Treatment]
TR -->|Prescription issued| RX[Prescriptions]
TR -->|Treatment completed| MR[Medical records]
TR -->|Treatment completed| INV[Invoicing]
RX --> REG[National prescription registry]
MR --> NHS[National healthcare system]
Each group has high cohesion (its parts serve one purpose): Scheduling knows nothing about prescriptions. When you build modules (see the post on pragmatic architecture and architectural drivers), each group becomes a module that owns its data and talks to others through pivotal events. For the next step, classifying subdomains (core, supporting, generic), settling bounded contexts and drawing a context map, see the post on DDD and package structure.
Exercises
Exercise 1: Event Storming a food-delivery order
The process: a customer orders on an app, the restaurant accepts, a driver picks up and delivers, the customer pays and rates. Do a Big Picture: list events, strike technical ones, mark pivotal events, group them. Then do Process level for the most important group (actors, commands, policies, read models).
Solution to Exercise 1
Events (technical ones like “Push notification sent”, “Map API called” removed): Order placed → Payment authorised (P) → Order accepted by restaurant (P) → Food ready → Driver accepted trip (P) → Order picked up → Order delivered (P) → Payment captured (P) → Rating submitted. Other branch: Order rejected by restaurant → Authorisation released.
Why pivotal: authorising and capturing money are hard to reverse (you need a refund); the restaurant accepting is an actor switch and cooking starts (cancelling later wastes ingredients); the driver accepting starts the delivery subprocess; delivered is the closing milestone.
Groups: Ordering · Payments · Restaurant (kitchen) · Dispatch and delivery · Ratings.
Process level for Dispatch:
- Actors: dispatch system, driver.
- Commands: “Find a driver near the restaurant”, “Accept trip”, “Confirm pickup”, “Confirm delivery”.
- Policies: “When food is almost ready (~5 minutes left), start looking for a driver”; “If nobody accepts within 3 minutes, widen the radius”; “A driver holds at most 2 orders at once”.
- Read models: recent driver locations, estimated cooking time, list of open trips.
- Hot spot: “The customer cancels after pickup: who pays?”.
- External systems: map service, payment gateway.
In code: “Order accepted by restaurant” is an integration event the Dispatch module listens to; the “nobody accepts in 3 minutes” policy is a stateful job/timer, not a rule inside an aggregate.
Remember
- Recall the Why → What → How question order and why open questions matter.
- Tell business events from technical events, and list the signs of a pivotal event.
- Map actors, commands, policies and read models to backend code.
- Compare Event Storming with Domain Storytelling and know how to combine them.
- Explain why pivotal events are candidates for module boundaries and integration events.
Interview questions
Junior
How are events named in Event Storming, and why?
In the past tense, in business language: “Appointment scheduled”, not “Schedule appointment” or “Button clicked”.
An event is a fact that already happened and can’t change. Technical events (API called, PDF exported) are removed because they say nothing about the business.
What’s the difference between as-is and to-be?
As-is is the current process, to-be is the desired process once the software exists.
Model as-is first to understand reality, including manual work (notebooks, spreadsheets). To-be is a wish and will keep changing during delivery.
Mid
What is a pivotal event and why does it matter?
An event that marks a milestone, is hard to reverse, and often switches actor or starts a subprocess. It hints at the boundary between subprocesses.
Example: “Invoice sent” can only be fixed with a correcting invoice. In the design, pivotal events are usually integration events between modules, and need compensation instead of rollback.
At Process level, what is a policy and how does it become code?
A policy is a business rule: under which conditions something must or must not happen.
Two forms: a blocking rule (“no insurance, no appointment”) lives in the aggregate/service and runs synchronously; a reactive rule (“treatment completed, so prepare the invoice”) is a listener that runs after commit and must be idempotent.
You join a company and are told “the requirements are all in the documents”. What do you do?
Still read them, but propose a few workshops with domain experts, because documents don’t replace walking the process yourself.
Start with informal coffee, then a Why/What/How meeting. Pick the most critical process for the first workshop and prepare it well, since you usually get one chance to build trust.
Senior
Compare Event Storming and Domain Storytelling. When do you use which?
Event Storming finds “what happened” and suits big groups and event-driven systems; Domain Storytelling finds “who does what with what” and suits small groups and non-technical people. Best is to combine them.
Send a domain story first so everyone shares the flow, then Event Storm to find events, policies, hot spots and boundaries. Domain Storytelling misses obvious areas; Event Storming turns chaotic with a weak facilitator.
From an Event Storming result, how do you split modules or services?
Take the highly cohesive groups as module candidates, check them against pivotal events, actor switches and changes in word meaning, then let each module own its data and exchange only events or APIs.
- The same word meaning different things in two groups signals two bounded contexts.
- Pivotal events crossing a boundary become integration events (an outbox so none are lost).
- Reactive policies between groups become idempotent listeners.
- Start as modules in one deployment unit; extract services only when a driver demands it.
How do you handle hot spots still on the wall after the workshop?
Each hot spot is an unsettled risk: give it an owner and an answer-by date, and record the decision when it comes.
Hot spots that affect boundaries or invariants must be settled before coding that area. Ones that can’t be settled yet get a design that’s easy to change: wrap the assumption in one place and note it in an ADR.
Useful phrases for interviews
- “I’d run the first workshop with two domain experts from the front desk.”
- “A business event is named in the past tense, like Appointment Scheduled.”
- “We parked the cancellation fee question as a hot spot and moved on.”
- “Invoice Sent is a pivotal event because it’s hard to reverse.”
- “The policy says no appointment without valid insurance.”
- “The doctor’s calendar is the read model for scheduling.”
- “In domain storytelling, the prescription is a work object.”
- “We modelled the as-is process first, then the to-be.”
- “Each group has high cohesion, so it’s a good module candidate.”
- “A reactive policy runs after commit, so the listener has to be idempotent.”
Notes based on the book Master Software Architecture: A Pragmatic Guide by Maciej “MJ” Jedrzejewski (2024), rewritten in my own words; the mapping to code, the Java example, the exercise and its solution are my own.