Choreography Saga

Consider a loan approval flowing through three services, entirely through events:

1. Loans Service approves a loan and publishes LoanApprovedEvent, containing the loan ID, account ID, and approved amount.
2. Accounts Service has a listener watching for LoanApprovedEvent. When one arrives, it deposits the approved amount into the customer's account and publishes FundsDepositedEvent.
3. Customer Service has a listener watching for FundsDepositedEvent. When one arrives, it updates the customer's credit profile to reflect the new loan and publishes CreditProfileUpdatedEvent.
4. Nothing listens for CreditProfileUpdatedEvent in this flow, so the chain naturally ends there. The saga is complete — not because anything declared it complete, but because there's nothing left to react.

Notice the shape: every service in the middle of the chain both listens for the previous step's event and publishes its own event for whoever comes next. That dual role — consumer and producer at once — is what lets the chain propagate without any service needing to know more than one hop in either direction. Accounts Service doesn't know Customer Service exists; it just knows that when funds get deposited, that fact is worth telling the world about.

This also means adding a new step to the process usually means adding a new listener somewhere, not modifying an existing one. If a new notifications service wants to email the customer when their credit profile updates, it just adds a listener for CreditProfileUpdatedEvent — none of the three existing services need to change at all. That's a genuine strength of choreography: extending a flow rarely touches code that's already working.

The cost of that strength shows up when you need to answer a different kind of question: "what is the full sequence of things that happen when a loan gets approved?" With choreography, answering that means finding every listener across every service and manually tracing which ones fire for which events — there's no single file you can open to read the answer.

A choreography step is, mechanically, nothing more than a regular event handler that happens to send a command instead of (or in addition to) updating a read model. There's no special "saga" annotation or framework support required — any component that can listen for an event and use a CommandGateway can participate in a choreography saga.

Two things are worth noticing about this code. First, the listener lives inside Accounts Service, alongside its other event handlers — there's nothing that marks it as "part of a saga" from the outside. Second, the listener has no idea what happens after FundsDepositedEvent gets published. It doesn't know Customer Service exists, doesn't know a credit profile is about to get updated, and doesn't need to. Its entire responsibility begins and ends with "when a loan gets approved, deposit the money."

This narrow responsibility is exactly what makes choreography easy to write and easy to test in isolation — you can unit-test this listener completely by publishing a LoanApprovedEvent and asserting that a DepositFundsCommand gets sent, without needing to know or care about the rest of the saga at all.

@Component
public class LoanApprovedListener {

    private final CommandGateway commandGateway;

    public LoanApprovedListener(CommandGateway commandGateway) {
        this.commandGateway = commandGateway;
    }

    @EventHandler
    public void on(LoanApprovedEvent event) {
        commandGateway.send(new DepositFundsCommand(event.getAccountId(), event.getLoanAmount()));
        // If this command succeeds, AccountAggregate applies FundsDepositedEvent —
        // which Customer Service listens for next, continuing the chain.
    }
}

Real-world processes fail partway through. If the deposit into the customer's account fails — insufficient permissions, a downstream system down, a business rule violation — the loan that was already approved needs to be undone. This is a compensating transaction: not a rollback in the database sense, but a new, explicit action that reverses the effect of an earlier step.

In choreography, compensation uses exactly the same mechanism as the happy path: a service listens for a failure event and reacts by sending a command against its own aggregate.

The elegance here is real. Loans Service doesn't need a special "saga-aware" mode to participate in compensation — it just adds one more listener, for DepositFailedEvent, alongside whatever other listeners it already has. When that event arrives, it sends CancelLoanCommand against its own LoanAggregate, undoing the approval it granted earlier. From Loans Service's point of view, this is no different from reacting to any other event; it just happens to be undoing its own past action rather than reacting to someone else's.

This symmetry — happy path and compensation both implemented as plain event listeners — is one of choreography's more attractive properties. There's no separate compensation framework to learn, no special state machine to configure. Each service is simply responsible for knowing how to undo the one thing it did, and for listening for whatever event signals that it needs to.

@Component
public class DepositFailedListener {

    private final CommandGateway commandGateway;

    public DepositFailedListener(CommandGateway commandGateway) {
        this.commandGateway = commandGateway;
    }

    @EventHandler
    public void on(DepositFailedEvent event) {
        // Compensation: Loans Service reacts to someone else's failure
        // by undoing its own earlier step.
        commandGateway.send(new CancelLoanCommand(event.getLoanId()));
    }
}

Choreography's biggest weakness only shows up once a process outgrows three tidy services. With loan approval spanning Loans, Accounts, and Customer Service, the whole flow is genuinely easy to hold in your head. Now imagine seven or eight services, each one listening for two or three different events from two or three different neighbors, some of them publishing events that trigger yet more listeners two hops away.

At that point, the "plan" — the full sequence of what happens when a loan gets approved — doesn't live anywhere in the code. It exists only as an emergent pattern that you'd have to reconstruct by opening every service, finding every @EventHandler, and manually tracing which listener reacts to which event. There is no single file, no single class, that shows the whole picture.

A second, subtler mistake is forgetting that every listener in the chain needs to independently handle event redelivery, out-of-order delivery, and partial failure. Because there's no central coordinator tracking saga state, there's also no central place enforcing that the chain behaves correctly under those conditions — each service has to get it right on its own, every time.

The honest fix, when a choreography saga starts to feel unwieldy, isn't to add more documentation describing the implicit flow — it's to reach for a saga with an explicit, centrally visible plan instead.