Spring CQRS Event Sourcing Reference

A comprehensive reference implementation of Command Query Responsibility Segregation (CQRS) and Event Sourcing patterns using Spring Boot 3 and Java 21.

Overview

This project demonstrates how to implement CQRS and Event Sourcing in a modern Spring Boot application. It includes:

• Domain-Driven Design with aggregates and domain events
• Event Sourcing for persisting state changes as events
• CQRS with separate command and query models
• Event-driven architecture with event handlers for projections
• REST API for commands and queries
• Complete order management example domain

Architecture

Key Components

1. Domain Layer

   • AggregateRoot: Base class for aggregates with event sourcing capabilities
   • DomainEvent: Base class for all domain events
   • Order: Example aggregate implementing business logic

2. Command Side (Write Model)

   • Commands: CreateOrderCommand, AddOrderItemCommand, etc.
   • Command Handlers: Process commands and interact with aggregates
   • Event Store: Persists domain events

3. Query Side (Read Model)

   • Projections: Denormalized views optimized for queries
   • Event Handlers: Update projections when events occur
   • Query Services: Provide read access to projections

4. Infrastructure

   • EventStore: Interface for event persistence
   • JpaEventStore: JPA implementation of event store
   • AggregateRepository: Repository for loading/saving aggregates

Getting Started

Prerequisites

• Java 21
• Maven 3.8+

Running the Application

mvn spring-boot:run

The application will start on http://localhost:8080

H2 Database Console

Access the H2 console at http://localhost:8080/h2-console

• JDBC URL: jdbc:h2:mem:eventstore
• Username: sa
• Password: (empty)

API Documentation

Command API (Write Operations)

Create Order

POST /api/orders
Content-Type: application/json

{
  "customerName": "John Doe"
}

Add Order Item

POST /api/orders/{orderId}/items
Content-Type: application/json

{
  "productName": "Laptop",
  "quantity": 2,
  "unitPrice": 999.99
}

Confirm Order

POST /api/orders/{orderId}/confirm

Cancel Order

POST /api/orders/{orderId}/cancel

Query API (Read Operations)

Get Order by ID

GET /api/orders/{orderId}

Get All Orders

GET /api/orders

Filter Orders

GET /api/orders?customerName=John&status=CONFIRMED

Example Usage

1. Create an order:

curl -X POST http://localhost:8080/api/orders \
  -H "Content-Type: application/json" \
  -d '{"customerName": "John Doe"}'

2. Add items to the order:

curl -X POST http://localhost:8080/api/orders/{orderId}/items \
  -H "Content-Type: application/json" \
  -d '{"productName": "Laptop", "quantity": 1, "unitPrice": 1200.00}'

3. Confirm the order:

curl -X POST http://localhost:8080/api/orders/{orderId}/confirm

4. Query the order:

curl http://localhost:8080/api/orders/{orderId}

Testing

Run the tests with:

mvn test

License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.