A simple description of how Event Modeling works for software documentation can be found here
Event Modeling is excellent for documenting Event Sourcing based systems. But can existing systems also be documented with it?
First, let’s clarify one of the most important questions
Is It Worth the Effort?
Documenting an existing system from scratch? The effort doesn’t pay off, does it?
The answer is the same as always… it depends
How long do you plan to maintain and further develop the system for more than 12 months?
Does onboarding new employees take much longer than it should?
Is it planned in the foreseeable future that parts of the system will be redeveloped and possibly even extracted as separate services from the existing system?
If the answer to only one of these questions is “Yes,” there’s a high probability that the initial effort for system documentation will quickly pay off.
What Are the Benefits
Information Completeness
This is the most important reason why I would consider (post-)documentation with Event Modeling for every system. Event Modeling allows you to easily check at every step which data is used, where the data comes from, and how the data is passed on.
The one thing you must get right is absolute clarity about data flows in your system
Documentation of Dependencies
You can see at a glance where the data you’re working with comes from and also where encapsulation is not correct, because you might be accessing tables that belong to other systems.
Easy Onboarding
As always with Event Modeling - even for existing systems, we document functionality readable like a story, like a book from beginning to end.
How Do You Document Legacy Applications?
The basic approach has already been described by Adam Dymitruk in (3). The goal of the description is to document the data flows in a way that they are comprehensibly prepared.
As Adam so nicely describes it:
We document what remains when we pull the plug on the system.
The documentation can be divided into a handful of patterns.
For a refresher, here are the familiar patterns from Event Modeling
Buying cinema tickets
Since all systems can be described with these patterns, this also works for existing systems.
Instead of using events as the persistence medium, however, most existing systems work with a (relational) database or a distributed message broker like Apache Kafka
Simple example - A software system for operating a cinema.
First use case - the software should allow buying cinema tickets.
Buying cinema tickets
It’s important here that besides the patterns, we document how the data is stored in the system. So we could imagine a “Reservations” table.
Buying cinema tickets with tables
From this diagram alone, we already get valuable information. We apparently store a separate reservation for each seat in a cinema hall including the reservation date and a flag whether paid or not.
Let’s assume the external payment system confirms the card payment. After that, the flag in the database is set to “1”. The reservation becomes a purchase. However, only one payment was confirmed.
Payment process
Additionally, we have a background process that periodically checks the reservations for their expiration date. Reservations are valid for 30 minutes. We also see here that reservations are deleted directly upon expiration. No chance to get the tickets after expiration.
Reservation process
These rules can be mapped via policies in the Event Model to make clear which rules apply. For each of these policies there must be a unit test. This is where the business logic lives.
Policies
Besides the purchase process, there are apparently other systems that access the Reservations table, for example Reporting.
For reporting, the performance per showing is calculated from the total capacity of a cinema hall (Rooms table) and the paid reservations (Reservations table).
Reporting
Conclusion
Even for existing systems, an Event Model can be created with manageable effort. It doesn’t matter how the system is technically structured. The Event Model is technology-neutral at first.
But the model allows you to think easily about the system.
We see how data flows through the system.
And we already have the roadmap to make improvements. Instead of aggregating the paid reservations for reporting, for example, it might make sense to provide a “MovieScreeningReportGenerated” event after a showing ends that already pre-calculates the necessary information. (And this may of course initially be stored in its own Reporting table.)
I can help you document your existing systems and prepare important technical decisions.
The first step is a simple Event Modeling workshop.
Book a free 15-minute call now and I’ll show you what possibilities we have. I look forward to getting to know you.
Ready to Learn More?
My book “Understanding Eventsourcing” gives you the blueprint. But reading alone will take your team too long.
I can teach your team how to build these blueprints faster and skip the whole trial-and-error phase. Let’s have a chat about how this applies to your project.
Still 2 Team-Spots left for the Event Modeling Workshop this month.
Want to learn how to apply Event Modeling and Event Sourcing in practice?
Follow the Online Course “Implementing Eventsourcing” - comes with a Lifetime Event Modeling Toolkit License.
Links
(1) Documenting Software with Event Modeling
(2) What is Event Modeling? by Adam Dymitruk
(3) Event Modeling Traditional Systems? by Adam Dymitruk