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.
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
refundIdas 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
- Merchant API publishes
RefundRequested{refundId, merchantId, amount}toshardpay.refunds.v1. - Billing service consumes, validates merchant balance, publishes
RefundApproved{refundId}. - Ledger service consumes, credits merchant account idempotently, publishes
RefundCompleted{refundId}. - 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.
// 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.