A modular monolith hotel software with DDD, CQRS, Ports & Adapters and Event-Driven support
This project took a lot of time and effort. If you like it, please consider giving it a ⭐ star!
6.5 Aggregate Tactical Pattern
6.5.1 Raising Domain Events Inside The Aggregate
EventStorming is a flexible workshop format for collaborative exploration of complex business domains.
Although event storming is typically a collaborative process involving the entire team, in this project I applied it individually. Although not collaborative in this case, the process still provided clarity and structure to the design.
You can explore the full event storming board in detail here.
“A model is a selectively simplified and consciously structured form of knowledge.”
- Eric Evans, Domain Driven Design, Page 12
The system has undergone significant evolution since my initial modeling attempts, which began with simple paper sketches.
Although the domain itself is relatively straightforward, the design process presented several complex decisions.
One notable example was the choice to define RoomType as a separate aggregate—an approach that required considerable deliberation.
Another challenging decision involved removing the Availability class in favor of dynamically checking existing reservations when evaluating the availability of a reservation request. These are just a few examples of the many thoughtful trade-offs made throughout the design process.
The image below displays some of the early conceptual sketches created at the outset of the project. At that time, RoomType was treated merely as an enumeration, and the Availability class was directly associated with the Room.
The current version of the UML model is shown below:
The complete UML model is available here.
Reservation made directly by the customer online.
-
Customer visits the booking site and selects dates and number of guests.
-
Site checks available rooms and returns suitable room types via:
GET /api/reservations/availability -
Customer selects room type, enters personal and card details.
-
Site sends request to:
POST /api/reservations/create-online -
The system sends the reservation code, confirmation code and other details to the customer via SMS and email.
This refers to a reservation made over the phone by a customer, where the receptionist inputs the details manually.
-
Customer calls and provides necessary reservation details (dates, name, contact info, number of guests, etc.).
-
Receptionist checks room availability via:
GET /api/reservations/availability -
Receptionist confirms availability and enters reservation details using:
POST /api/reservations/create-online -
The system sends the reservation code, confirmation code and other details to the customer via SMS and email.
Customer walks in and wants to book and check in immediately.
-
Customer provides check-in/check-out dates, guest count.
-
Receptionist checks availability:
GET /api/reservations/availability -
Receptionist creates the reservation:
POST /api/reservations/create-in-hotel -
Receptionist receives payment through cash or card
-
The system sends the reservation code, confirmation code and other details to the customer via SMS and email.
Customer logs in and cancels their reservation online.
-
Customer logs into their portal.
-
System fetches user reservations:
GET /api/reservations/user -
User selects reservation to cancel and enters confirmation code.
-
System sends cancellation request:
PUT /api/reservations/{reservationId}/cancel
Customer calls to cancel their reservation.
-
Customer gives reservation info (code or name + phone).
-
Receptionist fetches reservation:
GET /api/reservations/{reservationCode} OR POST /api/reservations/customer -
Receptionist asks for confirmation code.
-
Receptionist cancels the reservation:
PUT /api/reservations/{reservationId}/cancel
Customer arrives and wants to check in.
-
Customer provides reservation code or name and phone number.
-
Receptionist fetches the reservation:
GET /api/reservations/{reservationCode} OR POST /api/reservations/customer -
Receptionist asks for confirmation code.
-
Receptionist checks in the customer:
PUT /api/reservations/{reservationId}/check-in -
Receptionist fetches room details:
GET /api/rooms/{roomId} -
Receptionist gives keys to the guest.
Customer wants to check out.
-
Customer provides reservation code or name and phone.
-
Receptionist fetches reservation:
GET /api/reservations/{reservationCode} OR POST /api/reservations/customer -
Receptionist checks out the reservation:
PUT /api/reservations/{reservationId}/check-out -
Reservation is marked as checked-out, making the room available for future reservations.
-
Receptionist collects keys.
-
A module may only depend on the integration submodule (e.g., facades, integration events) of another module. (This is explained in detail in the Modules & Integration section.)
-
The domain model or read model of a module must not be accessed or used by other modules. Instead, communication should occur through well-defined contracts.
-
Each module maintains its own data in a separate schema. Shared data between modules is not allowed.
-
All assumptions and guidelines regarding aggregates from the Domain-Driven Design (DDD) book apply.
-
Business logic must not leak into the application layer. (Follow the principle of "Tell, Don’t Ask.")
-
Dependencies of both the domain submodule and the integration submodule must be inverted, adhering to the Dependency Inversion Principle.
-
Each module must modify only one aggregate instance per transaction.
"And a properly designed bounded context modifies only one aggregate instance per transaction in all cases."
- Vaughn Vernon, Effective Aggregate Design Part 1
When a transaction involves multiple aggregates or modules, we rely on eventual consistency.
However, in this project, we aren't even encountering typical issues related to eventual consistency, since it's currently implemented as a modular monolith.
-
Identity Access: Responsible for user authentication and provides access to current user information for other modules.
-
Reservation (core) : Provides the main features of the application (e.g., create, cancel, check-in, etc.).
-
Room Management: Enables managers to manage rooms and room types (e.g., add, remove, etc.).
-
Payment: Handles payment processing and storage.
-
Notification: Sends notifications to customers via SMS and email for various events.
-
Shared: Contains common interfaces and shared domain (kernel) objects. Major modules depend on this module to reuse boilerplate code.
-
Security: Handles endpoint filtering and authorization.
-
Applicationmain: Responsible for starting the entire application.
I paid close attention to managing the dependencies between modules and made a strong effort to keep them loosely coupled.
Each module that is expected to be used by others contains an integration submodule. This submodule includes elements such as facades, integration events, and contracts, which serve as translators between dependent modules. The dependencies of the integration submodule are inverted; in other words, it has no dependencies on any other submodules within its own module, nor on any external modules. Service-like classes such as facades are defined as abstract within the integration submodule and are implemented by other submodules as needed.
To demonstrate how modules communicate, here's an example from this project which involves reservation cancellation and how it's handled by the payment module.
Below is the integration submodule of the reservation module:;
One of the integration events in the integration-reservation submodule is ReservationCancelledIntegrationEvent. This event is published by a domain event handler in the application-reservation submodule.
This event is then handled within the payment module, as shown below:
The payment module processes this event by depending solely on the integration-reservation submodule of the reservation module. Because the dependencies of the integration submodule are inverted, this approach minimizes coupling between the modules.
This part contains which patterns (high level and low level) are used in this project.
Most of the modules in this project use ports and adapters pattern.
Ports and Adapters is a software architecture pattern that aims to isolate the core logic of an application from external systems such as databases, user interfaces, messaging systems, and other services. It achieves this separation by introducing "ports" as interfaces through which the core application communicates, and "adapters" as implementations of those interfaces for specific technologies or infrastructures.
"Allow an application to equally be driven by users, programs, automated test or batch scripts, and to be developed and tested in isolation from its eventual run-time devices and databases."
- Alistair Cockburn, Hexagonal architecture the original 2005 article
Command Query Responsibility Segregation (CQRS) is a design pattern that segregates read and write operations for a data store into separate data models. This approach allows each model to be optimized independently and can improve the performance, scalability, and security of an application.
There are various ways to implement the CQRS pattern. Below is the approach used in this project:
As shown below, each controller uses command/query buses to dispatch incoming requests to the corresponding command/query handler.
The two typical saga implementation approaches are choreography and orchestration. Each approach has its own set of challenges and technologies to coordinate the workflow.
In the choreography approach, services exchange events without a centralized controller. With choreography, each local transaction publishes domain events that trigger local transactions in other services.
I used the choreography approach for this project. Below is the model illustrating the choreography-based saga:
Here is the event flow model of this project:
If you want to have a closer look, you can access to the event flow from here.
The screenshot below shows the console output log when a 'Create Online Reservation' request is made to the API. The event flow can also be observed in the logs.
While designing this project, certain parts seemed well-suited for the use of specific design patterns. For those parts, I applied the appropriate pattern. Here's an example from the notification module of the project :
The Aggregate is one of the key tactical patterns introduced in the book Domain-Driven Design by Eric Evans. It helps manage complexity and maintain consistency within the domain model.
Book definition:
An AGGREGATE is a cluster of associated objects that we treat as a unit for the purpose of data changes. Each AGGREGATE has a root and a boundary. The boundary defines what is inside the AGGREGATE. The root is a single specific ENTITY contained in the AGGREGATE. The root is the only member of the AGGREGATE that outside objects are allowed to hold references to, although objects within the boundary may hold references to each other
"Instead of dispatching to a domain event handler immediately, what if instead we recorded our domain events, and before committing our transaction, dispatch those domain events at that point? This will have a number of benefits, besides us not tearing our hair out."
- Jimmy Boggard, A better domain events pattern, 2014
In this approach, domain events are not published immediately when they occur. Instead, they are recorded within the aggregate root during the execution of business logic. These recorded events are then dispatched only after the aggregate has been persisted—ensuring consistency between the state changes and the events they produce.
To support this, all aggregate roots inherit from a shared abstract base class that provides the functionality to register domain events:
Below is an example from the Reservation aggregate root. This method demonstrates how a domain event is raised internally as part of the aggregate's behavior:
This pattern ensures that domain events remain tightly coupled with the aggregate's lifecycle, promoting consistency, maintaining encapsulation, and reducing the risk of side effects during business operations.
Unit tests focus on verifying business behaviors, not just individual methods or classes. Each test should reflect a meaningful scenario within the domain, ideally something that resonates with a business user. These tests are fast, isolated, and help validate the rules and logic embedded in aggregates and domain services.
Integration tests validate how multiple components of the system work together — such as repositories, external services, message handlers, and infrastructure code. These tests ensure that the system behaves correctly when all the pieces are wired together, often involving databases, HTTP endpoints, or messaging systems.
Mustafa Turgut
mstftrgt00@gmail.com