PoC .NET - CQRS

🔬 Proof of Concept of CQRS pattern in .NET using RabbitMQ, ReBus, State Machine, MediatR and Docker

Proof of Concept demonstrating the CQRS pattern in .NET 10 using MediatR, Rebus, RabbitMQ, Stateless State Machine, EF Core, and Docker.

Architecture Overview
Tech Stack
Project Structure
Order Lifecycle — State Machine
CQRS Flow
Getting Started
API Reference
Design Decisions

Architecture Overview

┌────────────────────────────────────────────────────────────────┐
│                        HTTP Client                             │
└───────────────────────────┬────────────────────────────────────┘
                            │  REST
┌───────────────────────────▼────────────────────────────────────┐
│                     CqrsPoC.API                                │
│  OrdersController  →  IMediator                                │
└────────┬──────────────────┬───────────────────────────────────-┘
         │ Commands         │ Queries
┌────────▼──────────────────▼────────────────────────────────────┐
│                  CqrsPoC.Application                           │
│                                                                │
│  ┌─────────────────────┐   ┌─────────────────────────────┐    │
│  │   Command Handlers  │   │      Query Handlers          │    │
│  │  CreateOrder        │   │  GetOrderQueryHandler        │    │
│  │  ConfirmOrder       │   │  GetAllOrdersQueryHandler    │    │
│  │  ShipOrder          │   └──────────────┬──────────────┘    │
│  │  CompleteOrder      │                  │                    │
│  │  CancelOrder        │   ┌──────────────▼──────────────┐    │
│  └────────┬────────────┘   │   IOrderRepository (read)   │    │
│           │                └─────────────────────────────┘    │
│           │ IEventPublisher                                    │
│  ┌────────▼────────────────────────────────────────────────┐  │
│  │              LoggingBehavior (pipeline)                  │  │
│  └─────────────────────────────────────────────────────────┘  │
└────────┬───────────────────────────────────────────────────────┘
         │
┌────────▼───────────────────────────────────────────────────────┐
│                  CqrsPoC.Infrastructure                        │
│                                                                │
│  ┌──────────────────────┐   ┌───────────────────────────────┐ │
│  │   AppDbContext       │   │     RebusEventPublisher       │ │
│  │   (EF Core InMemory) │   │     → IBus (Rebus)            │ │
│  │   OrderRepository    │   │     → RabbitMQ exchange       │ │
│  └──────────────────────┘   └──────────────┬────────────────┘ │
│                                            │ publishes        │
│                             ┌──────────────▼────────────────┐ │
│                             │  Event Handlers (Rebus subs)  │ │
│                             │  OrderCreatedEventHandler     │ │
│                             │  OrderConfirmedEventHandler   │ │
│                             │  OrderShippedEventHandler     │ │
│                             │  OrderCompletedEventHandler   │ │
│                             │  OrderCancelledEventHandler   │ │
│                             └───────────────────────────────┘ │
└────────────────────────────────────────────────────────────────┘
         │
┌────────▼───────────────────────────────────────────────────────┐
│                      CqrsPoC.Domain                           │
│                                                                │
│  Order (Aggregate Root)                                        │
│    └─ Stateless State Machine                                  │
│         Pending → Confirmed → Shipped → Completed              │
│         Pending/Confirmed → Cancelled                          │
└────────────────────────────────────────────────────────────────┘

Tech Stack

Concern	Library / Tool	Version
Framework	.NET / ASP.NET Core	10.0
CQRS Mediator	MediatR	12.x
Message Bus	Rebus	8.x
Message Transport	Rebus.RabbitMq (RabbitMQ)	10.x
State Machine	Stateless	5.x
ORM / Persistence	EF Core (InMemory for PoC)	10.0
API Docs	Swashbuckle / Swagger	7.x
Containerisation	Docker + Docker Compose	—

Project Structure

CqrsPoC/
├── CqrsPoC.sln
├── Dockerfile
├── docker-compose.yml
└── Src/
    ├── CqrsPoC.Contracts/          # Shared integration event records
    │   └── Events/
    │       ├── OrderCreatedEvent.cs
    │       ├── OrderConfirmedEvent.cs
    │       ├── OrderShippedEvent.cs
    │       ├── OrderCompletedEvent.cs
    │       └── OrderCancelledEvent.cs
    │
    ├── CqrsPoC.Domain/             # Pure domain — no framework deps
    │   ├── Entities/
    │   │   └── Order.cs            ← Aggregate root + state machine
    │   ├── Enums/
    │   │   ├── OrderState.cs
    │   │   └── OrderTrigger.cs
    │   └── Exceptions/
    │       ├── DomainException.cs
    │       └── OrderNotFoundException.cs
    │
    ├── CqrsPoC.Application/        # Use-cases, CQRS handlers
    │   ├── Commands/
    │   │   ├── CreateOrder/
    │   │   ├── ConfirmOrder/
    │   │   ├── ShipOrder/
    │   │   ├── CompleteOrder/
    │   │   └── CancelOrder/
    │   ├── Queries/
    │   │   ├── GetOrder/
    │   │   └── GetAllOrders/
    │   ├── Behaviors/
    │   │   └── LoggingBehavior.cs  ← MediatR pipeline (cross-cutting)
    │   ├── Interfaces/
    │   │   ├── IOrderRepository.cs
    │   │   └── IEventPublisher.cs
    │   └── DependencyInjection.cs
    │
    ├── CqrsPoC.Infrastructure/     # EF Core + Rebus implementations
    │   ├── Persistence/
    │   │   ├── AppDbContext.cs
    │   │   └── Repositories/
    │   │       └── OrderRepository.cs
    │   ├── Messaging/
    │   │   ├── RebusEventPublisher.cs
    │   │   └── Handlers/
    │   │       ├── OrderCreatedEventHandler.cs
    │   │       ├── OrderConfirmedEventHandler.cs
    │   │       ├── OrderShippedEventHandler.cs
    │   │       ├── OrderCompletedEventHandler.cs
    │   │       └── OrderCancelledEventHandler.cs
    │   └── DependencyInjection.cs
    │
    └── CqrsPoC.API/                # HTTP entry point
        ├── Controllers/
        │   └── OrdersController.cs
        ├── Program.cs
        ├── appsettings.json
        └── appsettings.Development.json

Order Lifecycle — State Machine

The Order aggregate embeds a Stateless state machine that enforces all valid lifecycle transitions at the domain level. Invalid transitions throw a DomainException, which the API maps to 400 Bad Request.

                    ┌─────────┐
                    │ Pending │ ◄─── Initial state on creation
                    └────┬────┘
          [confirm]      │       [cancel]
              ┌──────────┘──────────────┐
              ▼                         ▼
       ┌───────────┐             ┌───────────┐
       │ Confirmed │             │ Cancelled │ (terminal)
       └─────┬─────┘             └───────────┘
    [ship]   │       [cancel]         ▲
             │────────────────────────┘
             ▼
         ┌────────┐
         │Shipped │
         └────┬───┘
   [complete] │
              ▼
        ┌───────────┐
        │ Completed │ (terminal)
        └───────────┘

Each OrderDto response includes a permittedTriggers array so clients always know which transitions are available in the current state.

CQRS Flow

Command flow (write side)

HTTP PUT /api/orders/{id}/confirm
  └─► OrdersController.Confirm()
        └─► IMediator.Send(ConfirmOrderCommand)
              └─► LoggingBehavior (pipeline)
                    └─► ConfirmOrderCommandHandler
                          ├─► IOrderRepository.GetByIdAsync()
                          ├─► order.Confirm()          ← state machine fires
                          ├─► IOrderRepository.SaveChangesAsync()
                          └─► IEventPublisher.PublishAsync(OrderConfirmedEvent)
                                └─► Rebus IBus.Publish()
                                      └─► RabbitMQ exchange
                                            └─► OrderConfirmedEventHandler (subscriber)

Query flow (read side)

HTTP GET /api/orders/{id}
  └─► OrdersController.GetById()
        └─► IMediator.Send(GetOrderQuery)
              └─► LoggingBehavior (pipeline)
                    └─► GetOrderQueryHandler
                          └─► IOrderRepository.GetByIdAsync()
                                └─► OrderDto (projection)

Getting Started

Prerequisites

Docker Desktop (or Docker + Compose plugin)
.NET 10 SDK — only needed for local development without Docker

Run with Docker Compose

# Clone / navigate to the repo root
git clone <repo-url>
cd CqrsPoC

# Build and start both services (RabbitMQ + API)
docker compose up --build

# API Swagger UI  →  http://localhost:8080
# RabbitMQ UI     →  http://localhost:15672  (guest / guest)

To stop and remove containers:

docker compose down -v

Run Locally (without Docker)

Start RabbitMQ via Docker:

docker run -d \
  --name rabbitmq \
  -p 5672:5672 \
  -p 15672:15672 \
  rabbitmq:3.13-management-alpine

Run the API:

cd Src/CqrsPoC.API
dotnet run
# Swagger UI → https://localhost:5001  (or check the console output)

API Reference

Method	Endpoint	Description	Transition
`GET`	`/api/orders`	List all orders	—
`GET`	`/api/orders/{id}`	Get a single order	—
`POST`	`/api/orders`	Create a new order	→ Pending
`PUT`	`/api/orders/{id}/confirm`	Confirm a pending order	Pending → Confirmed
`PUT`	`/api/orders/{id}/ship`	Ship a confirmed order	Confirmed → Shipped
`PUT`	`/api/orders/{id}/complete`	Complete a shipped order	Shipped → Completed
`PUT`	`/api/orders/{id}/cancel`	Cancel a pending/confirmed order	→ Cancelled

Example: Create Order

curl -X POST http://localhost:8080/api/orders \
  -H "Content-Type: application/json" \
  -d '{
    "customerName": "Guilherme",
    "productName": "Mechanical Keyboard",
    "amount": 149.99
  }'
# → 201 Created  { "id": "3fa85f64-..." }

Example: Full lifecycle

ID="<paste-id-from-create>"

curl -X PUT http://localhost:8080/api/orders/$ID/confirm
curl -X PUT http://localhost:8080/api/orders/$ID/ship
curl -X PUT http://localhost:8080/api/orders/$ID/complete

# Check final state
curl http://localhost:8080/api/orders/$ID

Error responses

Domain and transition errors return RFC 7807 Problem Details:

{
  "status": 400,
  "title": "DomainException",
  "detail": "Cannot apply trigger 'Ship' when order is in state 'Pending'."
}

Design Decisions

Clean Architecture layers

Dependencies flow inward: API → Application → Domain.
Infrastructure implements interfaces defined in Application — so the domain and use-cases have zero framework dependencies.

MediatR pipeline behaviours

LoggingBehavior<TRequest,TResponse> is registered as an open generic pipeline behaviour, giving structured logging + timing for every Command and Query without touching individual handlers.

Rebus + RabbitMQ

Rebus acts as the integration event bus. After a command mutates state, the handler publishes a typed event record (IEventPublisher), which Rebus routes to RabbitMQ. Subscribers (also in Infrastructure) react asynchronously — decoupling side-effects from the command path.

The IEventPublisher abstraction in the Application layer means handlers never reference Rebus directly, keeping the transport swappable.

Stateless state machine inside the aggregate

The state machine lives inside the Order aggregate as a private field. It is rebuilt on every instantiation (including EF Core hydration), reads the persisted State column, and mutates it only through domain methods (Confirm(), Ship(), etc.).
This keeps the machine as an enforcement mechanism — not just documentation.

EF Core InMemory

Used for simplicity in this PoC. Swap UseInMemoryDatabase for UseSqlServer / UseNpgsql / etc. in Infrastructure/DependencyInjection.cs and add a migration to go production-ready.

Testing

The solution contains three test projects under the /Tests folder, covering the full testing pyramid.

Tests/
├── CqrsPoC.Tests.Unit/            # Fast, isolated — no I/O, pure logic
│   ├── Domain/
│   │   └── OrderStateMachineTests.cs    (26 tests)
│   └── Application/
│       ├── Commands/CommandHandlerTests.cs  (17 tests)
│       ├── Queries/QueryHandlerTests.cs     (8 tests)
│       └── Behaviors/LoggingBehaviorTests.cs (4 tests)
│
├── CqrsPoC.Tests.Integration/    # Real EF Core + real Rebus (in-memory transport)
│   ├── Persistence/
│   │   └── OrderRepositoryTests.cs      (8 tests)
│   ├── Messaging/
│   │   └── RebusEventHandlerTests.cs    (5 tests)
│   └── Infrastructure/
│       └── ApplicationPipelineTests.cs  (10 tests)
│
└── CqrsPoC.Tests.E2E/            # Full HTTP stack via WebApplicationFactory
    └── Endpoints/
        └── OrdersApiTests.cs            (20 tests)

Run all tests

dotnet test

Run by project

# Unit only
dotnet test Tests/CqrsPoC.Tests.Unit

# Integration only
dotnet test Tests/CqrsPoC.Tests.Integration

# E2E only
dotnet test Tests/CqrsPoC.Tests.E2E

Test strategy

Layer	What’s tested	Mocked
Unit	Domain state machine transitions, command/query handler orchestration, MediatR pipeline behaviour	`IOrderRepository`, `IEventPublisher`
Integration	EF Core repository CRUD, Rebus in-memory event delivery, full MediatR+handler pipeline	`IEventPublisher` only (no RabbitMQ)
E2E	All HTTP endpoints, status codes, response bodies, Problem Details errors, full lifecycle	`IEventPublisher` (Moq), RabbitMQ (InMemory Rebus transport), EF Core (InMemory DB)