Microservices Sample: Clean Architecture with CQRS, Event Sourcing & Saga Choreography

A production-grade sample demonstrating best practices for building microservices using:

Clean Architecture - Separation of concerns with clear layers
CQRS - Command Query Responsibility Segregation
Event Sourcing - Immutable event history as source of truth
Saga Choreography - Distributed transactions via event-driven communication
TDD - Test-Driven Development with outside-in approach
Kafka - Asynchronous inter-service communication

📋 Project Overview

Two microservices (Bounded Contexts) collaborate via events to fulfill a business requirement:

Saga: Project Creation Request

┌─ User requests to create a project ─┐
│                                     │
│    PROJECT SERVICE (Port 8082)      │
│    ├─ Creates project (PENDING)     │
│    └─ Publishes: ProjectCreationRequested
│                   │
│                   ├─→ [Kafka Topic] ─→
│                                    │
│    WORKSPACE SERVICE (Port 8081)   │
│    ├─ Validates quota (max 2)      │
│    ├─ If quota available:          │
│    │  └─ Publishes: ProjectCreationApproved
│    │                    │
│    │                    └─→ [Kafka Topic] ─→
│    │                                      │
│    │    PROJECT SERVICE                  │
│    │    └─ Updates: Project = ACTIVE    │
│    │                                      │
│    └─ If quota exceeded:           │
│       └─ Publishes: ProjectCreationDenied
│                    │
│                    └─→ [Kafka Topic] ─→
│                                      │
│                    PROJECT SERVICE   │
│                    └─ Updates: Project = REJECTED

🏗️ Architecture Layers

Clean Architecture Structure

Each Service follows:
├─ Presentation Layer (REST Controllers)
│  └─ User-facing HTTP API
│
├─ Application Layer (Handlers)
│  └─ Use case orchestration & event handling
│
├─ Domain Layer (Aggregates, Events, Repositories)
│  └─ Core business logic (framework-independent)
│
└─ Infrastructure Layer (Repositories, EventBus)
   └─ Database, messaging, external services

Key Design Patterns

Aggregate Pattern - Workspace & Project are aggregates with their own lifecycle
Repository Pattern - Abstraction for data persistence
Event Handler Pattern - Process domain events asynchronously
Saga Pattern - Choreography-based distributed transactions
Service Locator Pattern - Spring dependency injection

📁 Project Structure

microservices-sample/
│
├── shared/                           # Shared infrastructure & events
│   ├── src/main/java/
│   │   └── com/workspace/project/shared/
│   │       ├── events/               # Domain events (immutable facts)
│   │       │   ├── DomainEvent.java
│   │       │   ├── ProjectCreationRequested.java
│   │       │   ├── ProjectCreationApproved.java
│   │       │   └── ProjectCreationDenied.java
│   │       └── infrastructure/
│   │           └── KafkaEventBus.java
│   └── pom.xml
│
├── workspace-service/                # Workspace BC (Bounded Context)
│   ├── src/main/java/
│   │   └── com/workspace/project/workspace/
│   │       ├── WorkspaceServiceApplication.java  [Spring Boot App]
│   │       ├── domain/
│   │       │   ├── Workspace.java                [Aggregate Root]
│   │       │   └── WorkspaceRepository.java      [Repository Interface]
│   │       ├── application/
│   │       │   └── ProjectCreationRequestedHandler.java  [Event Handler]
│   │       └── infrastructure/
│   │           └── InMemoryWorkspaceRepository.java
│   ├── src/test/java/
│   │   └── ProjectCreationRequestedHandlerTest.java  [TDD Tests]
│   ├── src/main/resources/
│   │   └── application.properties
│   └── pom.xml
│
├── project-service/                  # Project BC (Bounded Context)
│   ├── src/main/java/
│   │   └── com/workspace/project/project/
│   │       ├── ProjectServiceApplication.java    [Spring Boot App]
│   │       ├── domain/
│   │       │   ├── Project.java                  [Aggregate Root]
│   │       │   └── ProjectRepository.java        [Repository Interface]
│   │       ├── application/
│   │       │   ├── CreateProjectHandler.java     [Command Handler]
│   │       │   ├── CreateProjectCommand.java     [Command DTO]
│   │       │   ├── ProjectCreationApprovedHandler.java  [Event Handler]
│   │       │   └── ProjectCreationDeniedHandler.java    [Event Handler]
│   │       ├── infrastructure/
│   │       │   └── InMemoryProjectRepository.java
│   │       └── presentation/
│   │           └── ProjectController.java        [REST API]
│   ├── src/test/java/
│   │   └── ProjectSagaHandlersTest.java  [TDD Tests]
│   ├── src/main/resources/
│   │   └── application.properties
│   └── pom.xml
│
├── docker-compose.yml                # Kafka infrastructure
├── pom.xml                           # Parent POM (multi-module)
└── README.md                         # This file

🚀 Quick Start

Prerequisites

Java 17+
Maven 3.8+
Docker & Docker Compose

1. Start Kafka Infrastructure

docker-compose up -d

Verify Kafka is running:

Kafka UI: http://localhost:8080

2. Build All Modules

mvn clean package -DskipTests

3. Run Services

Terminal 1 - Workspace Service:

cd workspace-service
java -jar target/workspace-service-1.0-SNAPSHOT.jar

Runs on http://localhost:8081
Listens for ProjectCreationRequested events

Terminal 2 - Project Service:

cd project-service
java -jar target/project-service-1.0-SNAPSHOT.jar

Runs on http://localhost:8082
Listens for ProjectCreationApproved and ProjectCreationDenied events

4. Run Tests

# Test all modules
mvn clean test

# Test specific module
mvn test -pl workspace-service
mvn test -pl project-service

🧪 Testing with Postman

Test Case 1: User with Quota (Approval)

User 001: Has 0 projects, can create 2 more.

POST http://localhost:8082/api/projects
Content-Type: application/json

{
  "userId": "user-001",
  "name": "My First Project",
  "description": "Building something amazing"
}

Response (201 Created):

{
  "projectId": "proj-abc123",
  "message": "Project created, awaiting approval"
}

Wait 2 seconds for saga to complete, then check status:

GET http://localhost:8082/api/projects/proj-abc123

Expected Response:

{
  "projectId": "proj-abc123",
  "userId": "user-001",
  "name": "My First Project",
  "description": "Building something amazing",
  "status": "ACTIVE"
}

Test Case 2: User at Quota (Denial)

User 003: Has 2 projects (at limit).

POST http://localhost:8082/api/projects
Content-Type: application/json

{
  "userId": "user-003",
  "name": "Third Project",
  "description": "Should be rejected"
}

Check status after 2 seconds:

GET http://localhost:8082/api/projects/proj-xyz789

Expected Response:

{
  "projectId": "proj-xyz789",
  "userId": "user-003",
  "name": "Third Project",
  "description": "Should be rejected",
  "status": "REJECTED"
}

Test Case 3: Watch Events in Kafka UI

Open http://localhost:8080 (Kafka UI)
Click Topics
View messages in:
- ProjectCreationRequested - requests from Project Service
- ProjectCreationApproved - approvals from Workspace Service
- ProjectCreationDenied - denials from Workspace Service

📊 Event Flow Example

Successful Project Creation

1. [Client] POST /api/projects {userId: user-001, name: "My Project"}
                ↓
2. [Project Service] CreateProjectHandler
   - Creates Project aggregate (status: PENDING_APPROVAL)
   - Saves to repository
   - Publishes: ProjectCreationRequested
                ↓ [Kafka]
3. [Workspace Service] ProjectCreationRequestedHandler
   - Loads Workspace(user-001) → has 0 projects
   - Checks: canCreateProject() → true
   - Increments: projectCount = 1
   - Saves Workspace
   - Publishes: ProjectCreationApproved
                ↓ [Kafka]
4. [Project Service] ProjectCreationApprovedHandler
   - Loads Project aggregate
   - Calls: project.approve()
   - Updates status: PENDING_APPROVAL → ACTIVE
   - Saves Project
                ↓
5. [Client] GET /api/projects/{id}
   Response: {"status": "ACTIVE", ...}

🧬 TDD Approach: Outside-In

This project demonstrates Test-Driven Development with the outside-in strategy:

1. Write Failing Tests

@Test
void shouldApproveProjectWhenUserHasQuota() {
    // Arrange: Create mock workspace with 0 projects
    Workspace workspace = new Workspace("ws-001", "user-001", 0);
    when(repository.findByUserId("user-001")).thenReturn(Optional.of(workspace));

    ProjectCreationRequested event = new ProjectCreationRequested(...);

    // Act
    handler.handle(event);

    // Assert: ProjectCreationApproved should be published
    verify(eventBus).publish(ArgumentMatchers.any(ProjectCreationApproved.class));
}

2. Implement Minimal Code

public class ProjectCreationRequestedHandler {
    public void handle(DomainEvent event) {
        Workspace workspace = workspaceRepository.findByUserId(userId).get();

        if (workspace.canCreateProject()) {
            workspace.incrementProjectCount();
            workspaceRepository.save(workspace);
            eventBus.publish(new ProjectCreationApproved(...));
        }
    }
}

3. Refactor with Confidence

Tests remain unchanged while implementation improves.

🔑 Key Concepts

Clean Architecture Benefits

✅ Testability - Domain logic has no framework dependencies ✅ Maintainability - Clear separation of concerns ✅ Scalability - Easy to add new use cases ✅ Flexibility - Swap implementations (DB, messaging, etc.)

CQRS Benefits

✅ Performance - Optimize reads and writes separately ✅ Clarity - Commands (intentions) vs Events (facts) ✅ Flexibility - Different data models for different concerns

Event Sourcing Benefits

✅ Audit Trail - Complete history of all changes ✅ Debugging - Replay events to understand state ✅ Temporal Queries - Query state at any point in time ✅ Eventual Consistency - Natural fit for distributed systems

Saga Choreography Benefits

✅ Loose Coupling - Services don't call each other directly ✅ Asynchronous - Non-blocking inter-service communication ✅ Scalable - Services can scale independently ✅ Resilient - Failure in one service doesn't stop others

🔧 Configuration

Workspace Service Quotas

Edit /workspace-service/src/main/java/com/workspace/project/workspace/domain/Workspace.java:

private static final int MAX_PROJECTS = 2;  // Change this value

Pre-populated Test Data

Edit /workspace-service/src/main/java/.../WorkspaceServiceApplication.java:

@Bean
public WorkspaceRepository workspaceRepository() {
    repo.save(new Workspace("ws-001", "user-001", 0));  // user-001: 0 projects
    repo.save(new Workspace("ws-002", "user-002", 1));  // user-002: 1 project
    repo.save(new Workspace("ws-003", "user-003", 2));  // user-003: 2 projects
}

📈 Extending the System

Add a Notification Service

# Create new module
mkdir notification-service

# Subscribe to ProjectCreationApproved
public void handle(ProjectCreationApproved event) {
    // Send email/SMS to user
    notificationService.sendEmail(event.getUserId(), ...);
}

Add a Reporting Service

# Create new module
mkdir reporting-service

# Subscribe to all events
// Builds analytics database
// Provides reporting API

Switch to Database

Replace InMemoryWorkspaceRepository with PostgresWorkspaceRepository:

@Repository
public class PostgresWorkspaceRepository implements WorkspaceRepository {
    @Autowired
    private JpaRepository<WorkspaceEntity, String> jpaRepo;

    @Override
    public Optional<Workspace> findByUserId(String userId) {
        return jpaRepo.findByUserId(userId)
            .map(entity -> new Workspace(...));
    }
}

🐛 Troubleshooting

Kafka Connection Error

# Check if Kafka is running
docker ps | grep kafka

# Restart Kafka
docker-compose down
docker-compose up -d

Port Already in Use

# Kill process on port 8081
lsof -ti:8081 | xargs kill -9

# Kill process on port 8082
lsof -ti:8082 | xargs kill -9

Events Not Appearing

Verify Kafka is running: docker ps
Check service logs for errors
Verify topics exist in Kafka UI (http://localhost:8080)
Ensure both services are running

Tests Failing

# Run with verbose output
mvn test -X

# Run specific test
mvn test -Dtest=ProjectCreationRequestedHandlerTest

📚 Further Reading

📝 Summary

This sample demonstrates:

✅ Clean Architecture with distinct layers ✅ CQRS separating commands from queries ✅ Event Sourcing using Kafka as event store ✅ Saga Choreography for distributed transactions ✅ TDD with outside-in test approach ✅ Spring Boot for rapid service development ✅ Kafka for asynchronous messaging ✅ Production patterns ready for real systems

Use this as a template for your microservices projects!

Ready to run? Execute:

docker-compose up -d
mvn clean package -DskipTests
# Terminal 1
cd workspace-service && java -jar target/*.jar
# Terminal 2
cd project-service && java -jar target/*.jar

Then test with Postman following the examples above! 🚀

Name		Name	Last commit message	Last commit date
project-service		project-service
shared		shared
workspace-service		workspace-service
.gitignore		.gitignore
Postman-Collection.json		Postman-Collection.json
README.md		README.md
TODO.md		TODO.md
compose.yml		compose.yml
pom.xml		pom.xml

Latest commit

History

Folders and files

Repository files navigation