Microservices · Saga Choreography

Reference implementation of the Saga Choreography 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 Choreography pattern coordinates a distributed transaction without a central orchestrator. Each microservice listens for the events it cares about, performs its local work, and publishes the next event for downstream services to pick up. No single component knows the full flow — the saga emerges from the event chain.

This implementation models an e-commerce order: Order.API publishes OrderCreated, which Payment.API reacts to; on payment success, Payment.API publishes PaymentCompleted, which Stock.API reacts to — and so on. On failure, compensating events flow backwards.

Architecture

 Order.API  ──OrderCreated──▶  Payment.API  ──PaymentCompleted──▶  Stock.API
     ▲                              │                                │
     │                              │ on failure                     │ on failure
     └──────────PaymentFailed◀──────┘                                │
     └─────────────────────────StockNotReserved◀──────────────────────┘
                   (compensating events flow back)

Tech Stack

Layer	Technology
Runtime	.NET / ASP.NET Core
Messaging	MassTransit consumers (no state machine)
Message broker	RabbitMQ
Persistence	Entity Framework Core
Pattern	Saga (Choreography)

Project Structure

.
├── Order.API/      # Publishes OrderCreated; reacts to compensating events
├── Payment.API/    # Reacts to OrderCreated, publishes PaymentCompleted / PaymentFailed
├── Stock.API/      # Reacts to PaymentCompleted, publishes StockReserved / StockNotReserved
├── Shared/         # Event contracts shared across services
└── Microservices.Saga.Choreography.sln

Running Locally

docker compose up -d   # RabbitMQ
dotnet run --project Order.API
dotnet run --project Payment.API
dotnet run --project Stock.API

Choreography vs Orchestration

This repo is the decentralised twin of Microservices.Saga.Orchestration. Choreography wins on decentralisation and team autonomy; Orchestration wins on observability and easier flow reasoning. Pick based on team structure and operational tooling.

---

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.