Use Cases¶
ESDM was built for teams who are serious about Event Sourcing and Domain-Driven Design and want their model to stay coherent as the system grows. The use cases below describe the situations in which ESDM most clearly earns its keep.
Capturing a Model During Discovery¶
When a team runs Event Storming, Domain Storytelling, or any similar discovery format, the artifacts at the end of the day are usually photos and sticky notes. ESDM gives you a place to put those discoveries that survives the workshop.
You can write the events you discovered, the commands that produce them, the actors that issue those commands, and the Bounded Contexts that hold them, and you get immediate feedback on whether the model is internally consistent. An aggregate that owns no events, a command that nobody publishes, or a process manager without a starting condition – the linter flags those before they harden into assumptions.
For Domain Storytelling specifically, ESDM ships an extension that captures stories as their own kind of document and validates them under the same toolchain.
Keeping the Model and the Code in Sync¶
The most common failure mode for a domain model is not that the model is wrong, but that the model and the code drift apart. The team makes a refactoring decision in a sprint, the diagram on the wiki stays untouched, and six months later nobody trusts either source.
When the model lives in version-controlled YAML next to the code, drift becomes visible. A pull request that renames an aggregate has to update the model in the same change set, or the linter complains. A new event has to declare its publisher and its consumers, or the linter complains. The pressure of code review keeps the model honest.
This is the use case that benefits most from running esdm lint in CI. The check is fast, the failures are precise, and the cost of fixing a drift inline is much smaller than the cost of recovering a wrong model later.
Communicating with Stakeholders¶
A model expressed as YAML is also a model expressed in domain language. The names of aggregates, events, and commands are the same names the domain experts use. When you sit down with a product owner or a subject-matter expert, the model is a document you can read together, paragraph by paragraph.
The esdm view command renders an ESDM model as a hierarchical summary – Domain, Subdomains, Bounded Contexts, Consistency Units, the events and commands they own. It is the closest thing to a model overview that you can produce on demand and trust to match the source. For more depth, the Given-When-Then extension lets you capture concrete behavioral scenarios alongside the model, in the format domain experts already recognize from BDD.
Governing a Multi-Team System¶
In a single-team system, the rules of Event Sourcing tend to be implicit – everyone knows them, and they don't need to be written down. In a system with multiple teams and shared bounded contexts, what one team assumes about another's events becomes load-bearing, and assumptions diverge fast.
ESDM makes those contracts explicit. A context mapping declares the relationship between two bounded contexts. A cross-context event reference is a fact, not a guess. When two teams agree on a contract and write it down in the model, the linter holds them to it.
Where to Go Next¶
To start using ESDM in any of these scenarios, install it and run through Your First Model. If you want to understand which artifacts ESDM models and which it doesn't, the Concepts section is the next step.