Orchestration vs Choreography

There are two main approaches for managing distributed transactions: Orchestration and Choreography. Sagaweaw chose Orchestration for specific reasons.

---

Choreography (Event-Driven)

In choreography, each service reacts to events and emits new events. There is no central coordinator.

┌─────────┐    event    ┌─────────┐    event    ┌─────────┐
│ Service │ ──────────► │ Service │ ──────────► │ Service │
│    A    │             │    B    │             │    C    │
└─────────┘             └─────────┘             └─────────┘
     ▲                                               │
     └───────────────── event ◄──────────────────────┘

Pros

• Low coupling
• Independent services
• Scales horizontally

Cons

• Hard to debug — "where is my transaction?"
• Implicit flow — logic scattered across handlers
• Complex compensation — who knows the reverse order?
• Poor observability — requires correlation IDs + distributed tracing

---

Orchestration (Sagaweaw)

In orchestration, a central coordinator (Sagaweaw) controls the flow and knows exactly the state of each saga.

                    ┌─────────────┐
                    │  Sagaweaw   │
                    │ Orchestrator│
                    └──────┬──────┘
                           │
         ┌─────────────────┼─────────────────┐
         │                 │                 │
         ▼                 ▼                 ▼
    ┌─────────┐       ┌─────────┐       ┌─────────┐
    │ Service │       │ Service │       │ Service │
    │    A    │       │    B    │       │    C    │
    └─────────┘       └─────────┘       └─────────┘

Pros

• Explicit flow — declarative code
• Native observability — REST API with metrics and audit
• Automatic compensation — guaranteed reverse order
• Debuggable — centralized logs per saga

Cons

• Single point of coordination (mitigated with HA)
• Coupling to the orchestrator

---

Why We Chose Orchestration

ADR-005: Architecture Decision

Context: Critical financial systems require complete auditability and predictable recovery.

Decision: Use centralized orchestration with state persisted in PostgreSQL.

Consequences:

• Each saga has a unique ID and complete history
• Compensations execute in deterministic order
• REST API shows exactly where each transaction stands
• Orchestrator must have high availability

---

Comparison

Aspect	Choreography	Orchestration
Flow definition	Implicit (events)	Explicit (code)
Observability	Requires effort	Native
Compensation	Manual	Automatic
Debugging	Hard	Easy
Coupling	Low	Medium
Complexity	Distributed	Centralized

---

When to Use Each

Use Choreography when:

• Services belong to different teams with independent deploy cycles
• No need for complex compensation
• Flows are simple (A → B → C without rollback)

Use Orchestration (Sagaweaw) when:

• Financial or critical transactions
• Automatic compensation is required
• Audit and observability are requirements
• Team wants declarative and testable code

---

Further Reading

• Step Types →
• Lifecycle →
• Introduction →