Microservices · Saga Orchestration

Reference implementation of the Saga Orchestration pattern in .NET — a standalone study project built to internalize distributed-systems design end-to-end, beyond what tutorials typically cover.

What This Project Demonstrates

The Saga Orchestration pattern coordinates long-running distributed transactions through a central orchestrator. When a multi-step business operation spans several microservices, the orchestrator drives each step, listens for completion / failure events, and triggers compensating actions when any step fails — preserving eventual consistency without distributed locks.

This project implements an e-commerce order flow (Order → Payment → Stock) where the SagaStateMachine.Service orchestrates state transitions via MassTransit's state machine.

Architecture

   ┌────────────┐    OrderCreated    ┌──────────────────────┐
   │  Order.API │ ──────────────────▶│ SagaStateMachine     │
   └────────────┘                    │  .Service            │
                                     │  (Orchestrator)      │
                                     └──────────────────────┘
                                          │           │
                              PaymentStart│           │StockReserve
                                          ▼           ▼
                                   ┌────────────┐  ┌────────────┐
                                   │ Payment.API│  │  Stock.API │
                                   └────────────┘  └────────────┘
                                          │           │
                                          ▼           ▼
                                   PaymentCompleted   StockReserved
                                          │           │
                                          └─────┬─────┘
                                                ▼
                                          OrderCompleted
                                          (or compensating
                                          rollback events)

Tech Stack

Layer	Technology
Runtime	.NET / ASP.NET Core
Orchestration	MassTransit + state machine
Message broker	RabbitMQ (AMQP)
Persistence	Entity Framework Core
Pattern	Saga (Orchestration) + compensating actions

Project Structure

.
├── Order.API/                 # Initiates the saga
├── Payment.API/               # Reacts to PaymentStarted, emits PaymentCompleted / PaymentFailed
├── Stock.API/                 # Reacts to StockReserve, emits StockReserved / StockNotReserved
├── SagaStateMachine.Service/  # The orchestrator — drives state transitions
├── Shared/                    # Shared events, contracts, message types
└── Microservices.Saga.Orchestration.sln

Running Locally

# Bring up RabbitMQ + databases
docker compose up -d   # if compose file present

# In separate terminals:
dotnet run --project Order.API
dotnet run --project Payment.API
dotnet run --project Stock.API
dotnet run --project SagaStateMachine.Service

POST an order to Order.API to start the saga; observe the state transitions through RabbitMQ management UI.

When to Use Orchestration vs Choreography

• Orchestration (this repo): central coordinator, easier to reason about, single point of failure, harder to scale teams independently.
• Choreography (see Microservices.Saga.Choreography): services react to each other's events with no coordinator — fully decentralized, harder to debug.

---

About

Built by Ali Kalantari — a Backend Developer specialising in regulated fintech systems (.NET, Python, multi-database, event-driven).

This repository is part of my Distributed Systems Reference Series: a set of standalone study projects, each focused on one pattern, that I keep as working references when implementing similar designs in production.

Browse the full series: github.com/Ali-Klnai?tab=repositories&q=Microservices.