The pinball architecture / chained-choreography anti-pattern

// Pinball: 7-step loan disbursement as chained choreography
// IntakeService → publishes LoanRequested
// VerificationService → hears LoanRequested → publishes VerificationCompleted
// CreditScoringService → hears VerificationCompleted → publishes ScoreReady
// ApprovalService → hears ScoreReady → publishes LoanApproved
// FundReservationService → hears LoanApproved → publishes FundsReserved
// DisbursementService → hears FundsReserved → publishes LoanDisbursed
// NotificationService → hears LoanDisbursed → sends SMS

// The flow is a chain: A → B → C → D → E → F → G
// Nobody owns the chain. Nobody knows the full picture.

package com.bank.support;

public class CustomerSupportProblem {

    // Priya calls: "Where is my loan application LOAN-5001?"
    // Support agent must:
    // 1. Check Intake Service logs for LOAN-5001
    // 2. Check Verification Service logs
    // 3. Check Credit Scoring Service logs
    // 4. Check Approval Service logs
    // 5. Check Fund Reservation Service logs
    // 6. Check Disbursement Service logs

    // This takes 15 minutes of log searching across 6 services
    // And if any service dropped the event silently? Nobody knows.

    // With orchestration:
    // sagaRepo.findBySagaId("LOAN-5001") → state: "FUNDS_RESERVED"
    // Answer in 1 second from one query
}

// Disbursement fails after funds are reserved and loan is approved
// Who compensates? In what order?

// Choreography attempt:
// DisbursementService → publishes DisbursementFailed
// FundReservationService → hears DisbursementFailed → releases funds
// ApprovalService → hears DisbursementFailed → revokes approval
// But what if ApprovalService processes BEFORE FundReservation?
// What if FundReservation's listener has a bug and misses the event?
// What if VerificationService also needs to be compensated?

// Compensation logic is smeared across every service
// The ordering is implicit and depends on event delivery timing
// Missed compensations leave money in a bad state

// Orchestration: compensations driven from ONE place
package com.bank.saga;

public class LoanSagaOrchestrator {

    public void compensateOnDisbursementFailure(String loanId) {
        // Compensations in explicit reverse order:
        fundReservationClient.releaseFunds(loanId);  // C5
        approvalClient.revokeApproval(loanId);         // C4
        // Verification and scoring are read-only, no compensation needed
        intakeClient.cancelApplication(loanId);        // C1
        sagaRepo.updateState(loanId, "COMPENSATED");
    }
}

// Choreography: compensation scattered, implicit, fragile
// Orchestration: compensation centralized, explicit, reliable

// Warning signs that you need orchestration:
// 1. You cannot answer "what state is this order/loan in?" from any single place
// 2. Rollback logic is scattered across failure event listeners
// 3. Changing the flow order (inserting a step) risks breaking the chain
// 4. Testing the end-to-end flow requires starting all services
// 5. Customer support spends 15 minutes searching logs for one request

// Keep choreography when:
// 1. Reactions are independent (notification, analytics, fraud scoring)
// 2. No coordination or ordering needed between reactions
// 3. Adding a new reactor should be zero-change

package com.bank.saga;

import org.springframework.statemachine.StateMachine;
import org.springframework.statemachine.config.StateMachineBuilder;

public class LoanSagaStateMachine {

    // Spring State Machine definition:
    // States: STARTED, VERIFIED, SCORED, APPROVED, FUNDS_RESERVED,
    //         DISBURSED, COMPENSATING, COMPENSATED, FAILED
    // Transitions:
    //   STARTED → VERIFIED (on VERIFICATION_COMPLETE)
    //   VERIFIED → SCORED (on SCORE_READY)
    //   SCORED → APPROVED (on LOAN_APPROVED)
    //   APPROVED → FUNDS_RESERVED (on FUNDS_RESERVED)
    //   FUNDS_RESERVED → DISBURSED (on DISBURSEMENT_COMPLETE)
    //   any → COMPENSATING (on STEP_FAILED)
    //   COMPENSATING → COMPENSATED (on COMPENSATION_COMPLETE)

    // Benefits:
    // - State is queryable at any time
    // - Transitions are explicit and testable
    // - Compensation path is a first-class transition
    // - State is persisted for crash recovery
}

// Temporal workflow (pseudocode):
// @WorkflowMethod
// public void processLoan(LoanRequest request) {
//     verify(request);       // retries automatically on failure
//     score(request);        // durable state survives restarts
//     approve(request);      // timeout triggers compensation
//     reserveFunds(request); // all state queryable via Temporal UI
//     disburse(request);     // version-safe for long-running workflows
// }

// WRONG: 7-step loan flow as chained choreography
// "We chose choreography for loose coupling"
// Result: nobody can track loan state, compensation is broken,
// changing the flow breaks event chains, testing requires all 7 services

// CORRECT: orchestrate the core flow
// LoanSagaOrchestrator owns the state machine
// Query state: sagaRepo.findByLoanId("LOAN-5001") → APPROVED
// Compensate: orchestrator drives in reverse from one place
// Test: mock the service clients, test the state machine in isolation

// ALSO CORRECT: choreograph the independent reactions
// After disbursement: publish LoanDisbursed event
// Notification, Statement, Analytics react independently

// Senior decision matrix:
// Simple, independent reactions     → Choreography
// Complex, ordered, compensatable   → Orchestration
// Long-running (hours/days)         → Temporal or Camunda
// Short, in-process state machine   → Spring State Machine
// Mixed flow                        → Hybrid (orchestrate core, choreograph fan-out)

// Never: god orchestrator (domain logic in the coordinator)
// Never: pinball (complex flow as chained events)

package com.bank.architecture;

public class ChoreographyVsOrchestration {
    public static void main(String[] args) {
        System.out.println("Choreography (independent reactions):");
        System.out.println("  After disbursement: publish LoanDisbursed");
        System.out.println("  Notification listens -> sends SMS");
        System.out.println("  Analytics listens -> updates dashboard");
        System.out.println("  Adding a new listener = zero change to existing services");
        System.out.println();
        System.out.println("Orchestration (ordered, stateful workflow):");
        System.out.println("  Orchestrator drives: verify -> score -> approve -> disburse");
        System.out.println("  State queryable: sagaRepo.findByLoanId('LOAN-5001')");
        System.out.println("  Failure at step 4: compensate steps 3, 2, 1 in order");
    }
}

Expected output:
Choreography (independent reactions):
  After disbursement: publish LoanDisbursed
  Notification listens -> sends SMS
  Analytics listens -> updates dashboard
  Adding a new listener = zero change to existing services

Orchestration (ordered, stateful workflow):
  Orchestrator drives: verify -> score -> approve -> disburse
  State queryable: sagaRepo.findByLoanId('LOAN-5001')
  Failure at step 4: compensate steps 3, 2, 1 in order