Example application demonstrating the use of CQRS and Event Sourcing within the domain of hotel reservations. #NoFrameworks
This project is a sandbox for exploring how CQRS+ES affects the design of a system. The hypothesis is that it will lead to a better design than a typical database-centric approach; a design that is easily testable and does not detiorate as features are added. To answer that question, the problem being solved needs to be complex enough.
This project strives to differ from your typical toy examples in that the problem domain is complex enough to warrant all the techniques being used. The solution has been simplified, but the implemented features are production quality.
Source Code: https://github.com/luontola/cqrs-hotel
master branch |
API container | Web container |
|---|---|---|
 |
 |
 |
- technical features
- event store
- aggregate roots (write model)
- projections (read model)
- process managers
- GDPR compliance
- business features
- making a reservation
- room allocation
- payment
- check-in, check-out
- changing the departure date
- changing the room
Here are some pointers for where to look first in the code.
The web application's entry point is index.js and the entry points for each page are in routes.js. The UI is a single-page application which uses React and Redux but otherwise tries to avoid frameworks.
The backend application's main method is in Application.java and the entry points for each operation are in ApiController.java. External dependencies are wired with Spring in Application, but the application core is wired in ApiController constructor. See there the command handlers and query handlers which are the entry point to the business logic.
The framework code is in the fi.luontola.cqrshotel.framework package. It contains in-memory and PostgreSQL implementations of the event store (the latter's PL/SQL scripts are in src/main/resources/db/migration), and base classes for aggregate roots and projections. CQRS with event sourcing requires very little infrastructure code, so you can easily write it yourself without external frameworks, which helps to reduce complexity.
To learn how the write models work, read how a reservation is made, starting from SearchForAccommodationCommandHandler and MakeReservationHandler. The handlers contain no business logic. Instead, they delegate to Reservation which does all the work. Read the AggregateRoot base class, including its documentation, to understand how it should be used.
Of particular interest is how easy it is to unit test event sourced business logic. See SearchForAccommodationTest and MakeReservationTest. The given/when/then methods are in the simple AggregateRootTester base class.
To learn how the read models work, read ReservationsView and the base class Projection. Unit testing is again simple: ReservationsViewTest. Unlike aggregate roots, projections can listen to all events in the system; for example CapacityView is based on events from both Rooms and Reservations.
The easiest way to run this project is to use Docker.
Start the application
docker-compose pull
docker-compose up -d
The application will run at http://localhost:8080/
View application logs (in --follow mode)
docker-compose logs -f api
Stop the application
docker-compose stop
Stop the application and remove all data
docker-compose down
To develop this project, you must have installed recent versions of Java (JDK), Maven, Node.js, Yarn and Docker. You can do a clean build with the ./build.sh script. You can run this project's components individually with the following commands.
Start the database
docker-compose up -d db
Start the API backend (if not using an IDE)
mvn spring-boot:run
Start the web frontend (with live reloading)
yarn install
yarn start
The application will run at http://localhost:8080/
You may also start just the frontend or backend using Docker if you're developing only one layer of the application.
docker-compose up -d api
docker-compose up -d web
This example was mostly inspired by the following resources.
For more resources visit Awesome Domain-Driven Design. Ask questions at the DDD/CQRS discussion group.