Home

Awesome

Build Test Coverage Maintainability Dependabot

Event Sourcing and CQRS Examples

This project aims to provide examples of how to use Event Sourcing and CQRS applied to a minimalistic bank context.

We assume the reader has basic knowledge of Event Sourcing and CQRS concepts.
If you want to brush up on the subject we suggest reading:

Domain overview

In this minimalistic bank, a client can open one or more accounts.
On each account, the client can deposit or withdraw money.
The history of an account's transactions is available to the client as well as a summary of the client's accounts.

Design choices

Architecture overview

  Event Store   Projections
    +----+        +----+
    |    |        |    |
    | DB |        | DB |
    +--+-+        +-+--+
      ^             ^
      |             |
+------------+------------+
|     |      |      |     |
|     |    Events   |     |
|     +------+----+ |     |
|     |      |    | |     |
|     +      |    v +     |
|   Domain   |   Read     |
|   Model    |   Model    |
|            |            |
+------------+------------+
|                         |
|           API           |
|                         |
+-------------------------+ 

Ports and Adapters

For the Domain Model, we chose the Ports and Adapters structure because we wanted to protect the domain logic from all the technical concerns.

For more information about it read here.

Package by Feature

For the Read Models, we chose the Package by Feature structure because we would not benefit from isolating the layers and instead we put all feature related parts close together.

For more information about it read here.

DDD and REST

There has been a myth of DDD and REST being incompatible due to DDD being all about behaviour whereas REST is all about state.
In this project we followed both techniques quite strictly and hope that the result shows that they can be well combined.
Note: We did not include REST hypermedia controls as we believe it is a big subject in itself and didn't want to shift focus from Event Sourcing and CQRS.

Event Sourcing and CQRS (finally!)

We have taken a pragmatic approach when combining Event Sourcing and CQRS. By the book, CQRS proposes a complete separation between the read/query and write/command sides, but that's not what we have here. The approach we've taken instead:

Events

Events are a thing from the past. It communicates a significant change that happened.

Idempotency when replaying events

When replaying events, we don't want to execute any business logic because we can't change history. We only want to do assignments.
A simple example is with a deposit event: instead of adding the deposited amount to the balance when replaying (business logic), we want the updated balance already available so that we can just assign it. This makes it possible to replay the event multiple times with the same outcome.

Ordering of events

In a distributed world, event timestamps are unreliable for ordering - machines have their own clocks.
Instead we can make the ordering explicit with an event version. In this project we use event versioning in two ways:

If you are interested in this topic, we also recommend reading about Lamport timestamps and Vector clocks as alternatives.

Trying it out

Requirements

Building the application

mvn clean verify

Starting the application

java -jar target/bank-service-1.0-SNAPSHOT.jar server src/environments/development.yml

Examples of use

Create a client

curl -v -X POST -H "Content-Type: application/json" -d '{"name":"Jane Doe", "email":"jane.doe@example.com"}' http://localhost:8080/clients

Check the created client in the response's 'Location' header.

Create an account for the client

curl -v -X POST -H "Content-Type: application/json" -d '{"clientId":"{CLIENT_ID}"}' http://localhost:8080/accounts

Check the created account in the response's 'Location' header.

Make a deposit to the account

curl -v -X POST -H "Content-Type: application/json" -d '{"amount":1000000}' http://localhost:8080/accounts/{ACCOUNT_ID}/deposits

Check that you created a millionaire!

curl -v http://localhost:8080/accounts/{ACCOUNT_ID}

More operations

Go ahead and check the code! :)

Contributing

If you would like to help making this project better, see the CONTRIBUTING.md.

Maintainers

Send any other comments, flowers and suggestions to André Schaffer and Dan Eidmark.

License

This project is distributed under the MIT License.