ddd-hexagonal-cqrs-es-eda

Complete working example of using Domain Driven Design (DDD), Hexagonal Architecture, CQRS, Event Sourcing (ES), Event Driven Architecture (EDA), Behaviour Driven Development (BDD) using TypeScript and NestJS.

Current release: 1.0.2. See the changelog, the backend architecture, and the Keycloak IAM architecture.

Table of Contents

• I. Introduction
  • Overview
  • Todo application business requirements
• II. Technologies and Technical Features
  • Technical Features
  • Technologies Used - Overview
• III. Quick start - running the ToDo App
  • Prerequisites
  • Running the app
• IV. Design Process and Decisions
  • Design Process - Event Storming
  • Design Decisions
• V. Running in development mode
  • A. Project Setup
  • B. Application Validation
  • C. Understanding the project structure
• VI. Conclusion
  • ❓ Questions

I. Introduction

Building complex software is really hard, and we learnt the hard way how important it is to design your software correctly from the beginning!

There is plenty of information out there on how to build resilient and maintainable software, but the difficulty is actually implementing it. So we went ahead and built a comprehensive example we wish we had when we started learning these concepts and technologies.

Our team has put a lot of effort into creating a clean, and modular code-base that comes as close as possible to production ready code, aiming to provide valuable insights into advanced software architecture concepts.

Overview

The objective of this project is to provide you a reference implementation on how to design and create maintainable and flexible software applications.

The code is written using Typescript and NodeJS, using the NEST framework, however, the concepts and patterns used are not bound to any specific technologies.

The project includes an over-engineered ToDo app that includes the patterns and principles that are necessary if you want your code to be easy to change, resilient and easy to maintain. Below we provide detailed instructions on how to run it

In addition, you will learn a great deal about software design and architecture patterns and principles such as:

• Hexagonal Architecture (or Ports and adapters)
• Domain Driven Design (DDD) and its tactical patterns
• Behaviour Driven Development (BDD)
• Event Driven Architecture (EDA)
• Command and Query Responsibility Segregation (CQRS)
• Eventual consistency
• Event Storming

There are many ways to implement these, so we're eager to get your feedback and open to answer any questions you may have. Join our Discord channel if you'd like to exchange some ideas on software design & development or if you have any questions.

Todo application business requirements

The todo application, is basically a simple todo application, with some tweaks.

The users should be able to register to the todo app. After they register, they should be able to login. After logging in, they should be able to add todos, to complete a todo, to uncomplete a todo (in case they made it complete accidentally), as well as modify the todo title. In the whole process they should be able to view his todos.

When a todo is completed, if this is the first completed todo, an email should be sent to the user to congratulate him for completing his first todo. This operation has to do mostly with the needs marketing team.

II. Technologies and Technical Features

Technical Features

• Observability
• Realtime client events
• Logging
• Tracing: Tracks requests that span through multiple modules/microservices
• Easy switching between modular monolith and microservices
• Authentication
• Authorization (Even at the repository level)
• OpenID Connect session renewal
• Automatic client code generation using OpenAPI
• Event-sourced Todo aggregate with a transactional outbox

Technologies Used - Overview

Here are listed some of the specific technologies used for the implementation of the project:

• Authentication: Keycloak through OpenID Connect Authorization Code Flow with PKCE
• Database - Persistence: PostgreSQL
• Testing: JEST
• External Communication Protocols: REST and server-sent events
• Frameworks: ΝestJS
• PubSub technology: NATS
• Message Streaming Technology: JetStream by NATS
• Container Technology: Docker
• Tracing-Observability: Jaeger, Grafana
• Metrics: Prometheus

Persistence and event delivery

PostgreSQL is the sole application database. IAM and Marketing use relational tables, while the Todo aggregate is rehydrated from an append-only event stream. Each Todo command writes its events, query projection, and outbox messages in one PostgreSQL transaction. The outbox relay then publishes domain events to NATS JetStream with retry and at-least-once delivery semantics. See the backend architecture for the transaction, concurrency, and consumer guarantees.

III. Quick start - running the ToDo App

Prerequisites

In order to run the application the following should have been installed on your local machine:

• Docker should be installed (link)
• docker-compose should be installed, if your docker installation does not install it automatically (link)

Running the app

In order to run the application you need to follow the steps below:

• Run:

 git clone https://github.com/bitloops/ddd-hexagonal-cqrs-es-eda.git

• Navigate to the folder:

cd ddd-hexagonal-cqrs-es-eda

• Run:

docker compose -p bitloops-todo-app up -d

from the terminal inside the project in order to download and run the necessary containers.

Then the ReactJS front-end application will be visible at: http://localhost:4173.

The development realm includes demo@example.com with password Todo-Demo-2026!. Keycloak runs at http://localhost:8090; its development admin credentials are admin / admin-development-only. These credentials must never be used outside local development.

<p align="center" style="margin-bottom: 0px !important;"> <img width="400" alt="image" src="https://github.com/bitloops/ddd-hexagonal-cqrs-es-eda/assets/1571105/4570473b-4e67-4050-9935-967acfe0b7c6" alt="Frontend application" align="center"> </p> <p align="center"> Frontend React JS application (new version using Vite and Redux!) </p>

IV. Design Process and Decisions

Design Process - Event Storming

We have chosen the Event storming technique to document the functionality and business logic of the todo application.

In general, Event storming is a collaborating modelling technique used to model complex domains, in order to align the software produced with the actual business logic. It matches perfectly with Domain Driven Design (DDD) as well as Event Driven Architecture (EDA).

If you want to know more for this technique, you can check the Theoretical Review at the end.

<p align="center" style="margin-bottom: 0px !important;"> <img width="900" src="https://storage.googleapis.com/bitloops-github-assets/Todo%20event%20stroming%20new.png" alt="Todo Event Storming" align="center"> </p>

As you can see after the collaborative discovery, we have identified the following bounded contexts:

• IAM: Has todo with the user registration and log in.
• Todo: This is the core subdomain of our application (see DDD)
• Marketing: This is a supporting subdomain (see DDD) of our Todo application.

In the process we have further split some bounded contexts (linguistic boundary), to more fine grained modules.

The processes of the system as were discovered are the following:

• User Log In process (IAM Bounded Context)
• User registration process (IAM Bounded Context)
• Todo process (Todo Bounded Context)
• Onboarding process (Marketing Bo