Skip to main content
PreparationZone Logo
PrepZone

Saga Pattern — Choreography

Services react to events without a central orchestrator — trade-offs for ShardPay refunds.

Pass checkpoint below

Why this matters

  • Not every multi-step flow needs a central orchestrator; simple refund chains suit choreography well.
  • ShardPay uses choreography for merchant refund flows (three services, clear event contracts) and orchestration for cross-shard transfers (five steps, strict ordering).
  • Debugging choreography requires excellent tracing — the flow lives in event chains, not one state table.
  • Interviewers ask you to compare both styles and pick based on complexity, team boundaries, and observability budget.
OrderPlaced
InventoryReserved
PaymentCaptured
PaymentFailed → ReleaseInventoryCompensate
Each service listens and publishes domain events. Failure triggers compensating events on the same log.

Event-driven saga without a coordinator

In choreography, there is no central saga DB. The debit service publishes TransferDebited; the credit service consumes it and publishes TransferCredited or CreditFailed; the debit service listens for CreditFailed and publishes DebitCompensated.

ShardPay's refund flow works this way: RefundRequested → billing validates → RefundApproved → ledger credits merchant → RefundCompleted → notification emails the merchant. Each handler is idempotent on refundId.

Key points

  • Choreography — decentralized saga where services react to domain events without a central coordinator. ShardPay's refund pipeline has no orchestrator DB — state is implied by the latest event in the chain.
  • Event chain — ordered causality via published events, not a central state machine. A failed credit emits CreditFailed; downstream handlers subscribe to compensation triggers.
  • Event contract — schema, versioning, and idempotency rules per topic. ShardPay uses Avro schemas in Schema Registry with refundId as the idempotency key on every handler.
  • Visibility cost — reconstructing "where is this refund?" requires tracing across topics. ShardPay compensates with OpenTelemetry links from each event handler span to the originating refundId.

When ShardPay chooses choreography

Choreography fits when the flow is short (≤4 steps), teams own services independently, and event contracts are stable. ShardPay's refund saga has three services with infrequent schema changes — a good fit.

Refund walkthrough

  1. Merchant API publishes RefundRequested{refundId, merchantId, amount} to shardpay.refunds.v1.
  2. Billing service consumes, validates merchant balance, publishes RefundApproved{refundId}.
  3. Ledger service consumes, credits merchant account idempotently, publishes RefundCompleted{refundId}.
  4. Notification service consumes, sends email — no compensation needed (at-most-once email is acceptable).

If ledger credit fails, it publishes RefundFailed{refundId, reason}. Billing listens and publishes RefundApprovalRevoked — no central orchestrator coordinates the rollback.

Java
// ShardPay refund choreography — ledger handler
@KafkaListener(topics = "shardpay.refunds.approved.v1")
public void onRefundApproved(ConsumerRecord<String, RefundApproved> record) {
    RefundApproved event = record.value();
    if (processedEvents.exists(event.refundId())) return;

    try {
        ledgerService.creditMerchant(event.merchantId(), event.amountCents());
        kafkaTemplate.send("shardpay.refunds.completed.v1",
            event.refundId(), RefundCompleted.from(event));
        processedEvents.mark(event.refundId());
    } catch (InsufficientFundsException e) {
        kafkaTemplate.send("shardpay.refunds.failed.v1",
            event.refundId(), RefundFailed.from(event, e.getMessage()));
    }
}

The rest of this guide is part of Pro

Free covers every fresher guide in full. Pro unlocks Senior, Staff and Architect guides across every track.

Still to come · 1 section

  • Choreography vs orchestration

Test yourself

Answer these before moving on — recall is what makes it stick.