Implementing a use case (IV) — Domain Events (I)

This post is part of Implementing a Use Case, a series of posts where I share my learnings on designing, architecting and implementing use cases. I suggest reading the previous posts where I already explained some concepts you might find here.

You can either take a look at the code of the application example or the different tags which show the state of the application at the moment of the post.

Previously, we saw how we can model our use cases in our code by making them explicit in the form of Commands and Command Handlers. Commands represent an intent, a request to our application to perform some action. When a use case is executed something has just happened in our system:

Use Case: Assign a reviewer to a Pull Request
Output: A reviewer was assigned to a Pull Request
Output: Pull Request reviewer assignation failed.

Business people use these terms to define what’s the expected behavior of a use case given some invariants. Also, depending on the result of the use case they can talk about next actions that should occur.

- Business expert: When the user is assigning a reviewer to a pull request we must check whether the pull request has reached or not the maximum number of reviewers allowed.
- Developer: Should we show an error message to the user?
- Business expert: No. If the maximum number of reviewers is reached let’s automatically upgrade her plan to premium and tell her that it’s free for one month.

In the conversation above we can observe the next flow: Assign reviewer to pull request -> Maximum Pull Request reviewers assignation reached -> Upgrade customer plan to premium -> Customer plan upgraded.

So, in the same way we were representing use cases in our code we can do with the facts that occur when they are executed. Therefore, we can define a Domain Event as something that has happened in the past and is modeled in past tense: MaxmumPullRequestReviewersAssignationReached, CustomerPlanUpgraded, etc.

Commands and Events are powerful tools to express in our code the language that is of interest to our business. There is a workshop technique called Event Storming which explains how we can make use of them as the base to facilitate the communication and find out the domain in which the software must operate.

An event is something that has happened in the past

— Greg Young, “What is a Domain Event?”

In addition to the communication and domain modeling benefits, there are others that can be highlighted:

• Domain Events can be persisted as a log that can tell you what has happened and when at any point in your system. Events must be immutable, they never can be changed.
• Events can be used as policy rules to identify that something must be performed as the reaction of something that happened in the past.
• As Domain Events contain the info that represents the fact that has happened, we can reprocess this information as many times as we want to reconstitute the current state of our application.
• Commands and Domain Events make easier the design of a system. You can think of your system as a list of use cases and the facts that can occur in each of them; and chain [Command, Event] tuples to model your business processes: Command -> Event -> Command -> Event -> …

This post is meant to be a short and concise introduction to the Domain Event concept. In the next post, it is shown an implementation example of Domain Events and how our code gets simplified when designed in an event driven fashion.