Distributed transaction patterns using orchestration and choreography
Design distributed transaction patterns using orchestration and choreography for microservices. Use when implementing saga patterns for complex workflows with compensating transactions and eventual consistency.
/plugin marketplace add melodic-software/claude-code-plugins/plugin install event-modeling@melodic-softwareThis skill is limited to using the following tools:
Use this skill when:
Design distributed transaction patterns using orchestration and choreography for microservices.
Before designing sagas:
docs-management skill for saga patternsWhy Sagas?
PROBLEM:
Distributed transactions across services are complex.
Traditional 2PC (Two-Phase Commit) doesn't scale.
SOLUTION:
Saga = Sequence of local transactions
Each step has a compensating action
Eventual consistency instead of ACID
┌─────────┐ ┌─────────┐ ┌─────────┐
│ Step 1 │───►│ Step 2 │───►│ Step 3 │
│ Tx + Cx │ │ Tx + Cx │ │ Tx + Cx │
└─────────┘ └─────────┘ └─────────┘
│ │ │
▼ ▼ ▼
Local Local Local
Transaction Transaction Transaction
Tx = Forward Transaction
Cx = Compensating Transaction
Choreography Pattern:
Services communicate through events.
No central coordinator.
Each service knows what to do next.
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Order │ │ Payment │ │ Inventory │
│ Service │ │ Service │ │ Service │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
│ │ │
│ OrderCreated │ │
│─────────────────►│ │
│ │ PaymentProcessed │
│ │─────────────────►│
│ │ │ InventoryReserved
│◄─────────────────┼──────────────────│
│ OrderConfirmed │ │
Characteristics:
✓ Loose coupling
✓ Simple services
✗ Hard to track
✗ Cyclic dependencies risk
Orchestration Pattern:
Central orchestrator coordinates the saga.
Services expose commands.
Orchestrator manages state.
┌─────────────────┐
│ Orchestrator │
│ (Saga Manager) │
└────────┬────────┘
│
┌────────────────┼────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Order │ │ Payment │ │ Inventory │
│ Service │ │ Service │ │ Service │
└─────────────┘ └─────────────┘ └─────────────┘
Characteristics:
✓ Clear flow visibility
✓ Easier debugging
✗ Single point of failure
✗ Coupling to orchestrator
// Order Service - Starts Saga
public class OrderService
{
private readonly IEventPublisher _events;
public async Task CreateOrderAsync(CreateOrderCommand cmd)
{
var order = new Order(cmd.CustomerId, cmd.Items);
await _repository.SaveAsync(order);
// Publish event to start saga
await _events.PublishAsync(new OrderCreated
{
OrderId = order.Id,
CustomerId = cmd.CustomerId,
TotalAmount = order.TotalAmount
});
}
// Handle compensation
public async Task HandleAsync(PaymentFailed @event)
{
var order = await _repository.GetAsync(@event.OrderId);
order.Cancel("Payment failed");
await _repository.SaveAsync(order);
await _events.PublishAsync(new OrderCancelled
{
OrderId = @event.OrderId,
Reason = "Payment failed"
});
}
}
// Payment Service - Reacts to OrderCreated
public class PaymentService
{
public async Task HandleAsync(OrderCreated @event)
{
try
{
var payment = await ProcessPaymentAsync(@event.OrderId, @event.TotalAmount);
await _events.PublishAsync(new PaymentProcessed
{
OrderId = @event.OrderId,
PaymentId = payment.Id
});
}
catch (PaymentException ex)
{
await _events.PublishAsync(new PaymentFailed
{
OrderId = @event.OrderId,
Reason = ex.Message
});
}
}
}
// Inventory Service - Reacts to PaymentProcessed
public class InventoryService
{
public async Task HandleAsync(PaymentProcessed @event)
{
try
{
await ReserveInventoryAsync(@event.OrderId);
await _events.PublishAsync(new InventoryReserved
{
OrderId = @event.OrderId
});
}
catch (InsufficientInventoryException)
{
// Trigger compensation
await _events.PublishAsync(new InventoryReservationFailed
{
OrderId = @event.OrderId
});
}
}
// Compensating action
public async Task HandleAsync(OrderCancelled @event)
{
await ReleaseInventoryAsync(@event.OrderId);
}
}
// Saga State Machine
public class OrderSaga : Saga<OrderSagaData>,
IAmStartedBy<OrderCreated>,
IHandle<PaymentProcessed>,
IHandle<PaymentFailed>,
IHandle<InventoryReserved>,
IHandle<InventoryReservationFailed>
{
protected override void ConfigureHowToFindSaga(SagaPropertyMapper<OrderSagaData> mapper)
{
mapper.MapSaga(s => s.OrderId)
.ToMessage<OrderCreated>(m => m.OrderId)
.ToMessage<PaymentProcessed>(m => m.OrderId)
.ToMessage<PaymentFailed>(m => m.OrderId)
.ToMessage<InventoryReserved>(m => m.OrderId)
.ToMessage<InventoryReservationFailed>(m => m.OrderId);
}
public async Task Handle(OrderCreated message, IMessageHandlerContext context)
{
Data.OrderId = message.OrderId;
Data.CustomerId = message.CustomerId;
Data.TotalAmount = message.TotalAmount;
Data.Status = SagaStatus.Started;
// Request payment
await context.Send(new ProcessPaymentCommand
{
OrderId = message.OrderId,
Amount = message.TotalAmount
});
}
public async Task Handle(PaymentProcessed message, IMessageHandlerContext context)
{
Data.PaymentId = message.PaymentId;
Data.Status = SagaStatus.PaymentCompleted;
// Request inventory reservation
await context.Send(new ReserveInventoryCommand
{
OrderId = message.OrderId
});
}
public async Task Handle(PaymentFailed message, IMessageHandlerContext context)
{
Data.Status = SagaStatus.Failed;
// Compensate: Cancel order
await context.Send(new CancelOrderCommand
{
OrderId = message.OrderId,
Reason = "Payment failed"
});
MarkAsComplete();
}
public async Task Handle(InventoryReserved message, IMessageHandlerContext context)
{
Data.Status = SagaStatus.Completed;
// Complete the saga
await context.Publish(new OrderCompleted
{
OrderId = Data.OrderId
});
MarkAsComplete();
}
public async Task Handle(InventoryReservationFailed message, IMessageHandlerContext context)
{
Data.Status = SagaStatus.Failed;
// Compensate: Refund payment
await context.Send(new RefundPaymentCommand
{
OrderId = Data.OrderId,
PaymentId = Data.PaymentId
});
// Compensate: Cancel order
await context.Send(new CancelOrderCommand
{
OrderId = Data.OrderId,
Reason = "Inventory unavailable"
});
MarkAsComplete();
}
}
public class OrderSagaData : ContainSagaData
{
public Guid OrderId { get; set; }
public Guid CustomerId { get; set; }
public decimal TotalAmount { get; set; }
public Guid? PaymentId { get; set; }
public SagaStatus Status { get; set; }
}
Compensation Principles:
1. SEMANTIC UNDO
Not always exact reverse
Example: Cancel order vs. un-create order
2. IDEMPOTENT
Can be called multiple times safely
Same result regardless of retries
3. NEVER FAIL
Compensation must succeed eventually
Use retries with backoff
4. ORDERED
Compensate in reverse order
Last step first, first step last
Compensation Flow:
Step 1 ─► Step 2 ─► Step 3 ─► FAILURE
│ │ │ │
│ │ │ ▼
│ │ └───► Compensate 3
│ │ │
│ └───────────────► Compensate 2
│ │
└─────────────────────────► Compensate 1
// Forward Transaction and Compensation Pairs
public class ReservationService
{
// Forward: Reserve inventory
public async Task<ReservationId> ReserveAsync(OrderId orderId, List<Item> items)
{
var reservation = new Reservation(orderId, items);
foreach (var item in items)
{
await _inventory.DecrementAsync(item.ProductId, item.Quantity);
}
await _repository.SaveAsync(reservation);
return reservation.Id;
}
// Compensating: Release reservation
public async Task ReleaseAsync(ReservationId reservationId)
{
var reservation = await _repository.GetAsync(reservationId);
if (reservation.Status == ReservationStatus.Released)
return; // Idempotent
foreach (var item in reservation.Items)
{
await _inventory.IncrementAsync(item.ProductId, item.Quantity);
}
reservation.Release();
await _repository.SaveAsync(reservation);
}
}
Retry Patterns:
1. IMMEDIATE RETRY
For transient failures
Network glitches, timeouts
2. EXPONENTIAL BACKOFF
Increasing delays
1s → 2s → 4s → 8s
3. CIRCUIT BREAKER
Stop retrying after threshold
Allow recovery time
4. DEAD LETTER QUEUE
Capture failed messages
Manual intervention
// Saga with Timeout
public class OrderSaga : Saga<OrderSagaData>
{
public async Task Handle(OrderCreated message, IMessageHandlerContext context)
{
// Set timeout for payment
await RequestTimeout<PaymentTimeout>(
context,
TimeSpan.FromMinutes(30));
await context.Send(new ProcessPaymentCommand { ... });
}
public async Task Timeout(PaymentTimeout timeout, IMessageHandlerContext context)
{
if (Data.Status == SagaStatus.AwaitingPayment)
{
// Payment didn't complete in time
await context.Send(new CancelOrderCommand
{
OrderId = Data.OrderId,
Reason = "Payment timeout"
});
Data.Status = SagaStatus.TimedOut;
MarkAsComplete();
}
}
}
# Saga Design: [Process Name]
## Overview
[What this saga accomplishes]
## Trigger
[What event starts this saga]
## Steps
| Step | Service | Action | Compensating Action |
|------|---------|--------|---------------------|
| 1 | [Service] | [Forward action] | [Compensation] |
| 2 | [Service] | [Forward action] | [Compensation] |
| 3 | [Service] | [Forward action] | [Compensation] |
## Flow Diagram
```text
[ASCII saga flow diagram]
| Failure Point | What Failed | Compensation Chain |
|---|---|---|
| After Step 1 | [Description] | Compensate 1 |
| After Step 2 | [Description] | Compensate 2 → 1 |
| Factor | Choreography | Orchestration |
|---|---|---|
| Coupling | Loose | Tighter |
| Visibility | Distributed | Centralized |
| Complexity | In events | In orchestrator |
| Debugging | Harder | Easier |
| Team structure | Independent teams | Central team |
| Failure handling | Distributed | Centralized |
| Best for | Simple flows | Complex flows |
When designing sagas:
For detailed guidance:
Last Updated: 2025-12-26
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.
Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.
Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.