The Unified Saga Model (USM) • Whitepaper & Specification
Natively Reactive (Non-Blocking)
Spaghetti-Less, Clean & Type-Safe

The Next Evolution of Saga Orchestration

Continuous STP & Pausable HITL in the Exact Same Pipeline.

The domain-centric, natively reactive (non-blocking) saga orchestration ecosystem for modern enterprise microservices. Built on Project Reactor, StackSaga executes high-throughput Straight-Through Processing (STP) and deliberate Human-in-the-Loop (HITL) wait-states with zero thread starvation, zero dedicated coordinator servers, and native support for the Spring Boot ecosystem.

OrderFulfillmentSaga.java — Natively Reactive, Non-Blocking Pipeline
Step 1 • STP

CheckCustomerEligibility

.asSync().noPause()

⚡ Sub-millisecond Non-Blocking
PAUSABLE HITL
Step 2 • Wait-State

3D-Secure / KYC Approval

.pauseUntilResume(24h)

💤 100% Threads Released
Step 3 • Resumption

Webhook / Consumer

sagaTemplate.resume(resumeKey, 15m)

🔄 Ingests via ResumeContext
Step 4 • Two-Stage

Dispatch Warehouse

.asAsync().invoker(...)

🛡️ Commit Barrier Protected

Architectural Guarantees for Modern Enterprise & Cloud-Native Microservices

0 Dedicated Servers

Domain-embedded in domain services — zero external orchestrator clusters or ESB infrastructure tax

Natively Reactive

Built on Project Reactor from the ground up — fully non-blocking execution at event-loop scale

100% Thread Freedom

Pausable HITL wait-states sleep safely in the Event Store without holding worker threads

Lock-Free Retries

Murmur3 token-ring consistent hashing coordinates distributed self-healing without locks

The Unified Saga Model (USM)

One Pipeline for Every Execution Style

Real-world enterprise transactions are rarely purely synchronous or purely asynchronous. StackSaga introduces the Unified Saga Model — a formal architectural specification published as a whitepaper that harmonizes instant STP execution, pausable wait-states, and broker dispatch within a single saga.

Pillar 1 • Outward Integration

Unified Saga Integration Patterns (USIP)

Governs how individual atomic steps communicate across the network with utility microservices, databases, or message brokers, manage thread/connection lifecycles, and enforce Event Store commit barriers.

  • Pattern 1 (Sync-Continuous): Sub-second automated RPC & DB executions.
  • Pattern 2 (Sync-Paused): Intentional wait-states with 100% thread release.
  • Pattern 3 (Async-Paused): Event Store Commit Barrier before broker emission.
Thread Safety • Zero Resource Leakage • Event Sourcing
Pillar 2 • Inward Navigation

Unified Saga Navigation Patterns (USNP)

Governs how the workflow routes across the saga graph, dynamically branches based on business rules, and unwinds historical executions via Deterministic Reverse Autopilot.

  • Deterministic Reverse Autopilot: Automatic LIFO compensation without manual reverse routing graphs.
  • Query State Pruning: Read-only query steps are pruned from rollback automatically.
  • 3-Phase Compensation: Pre-Executors and Post-Executors for complex multi-action rollbacks.
Symmetrical Rollback • Sealed Type Safety • Dynamic Branching

Explore the 3 Integration Patterns in Code

See how cleanly the Saga Execution Coordinator (SEC) coordinates each pattern using staged fluent builders.

Natively Reactive (Reactor Mono / Flux)
100% Compile-Time Type Safety: Notice .toNextExecutor(ReserveInventoryExecutor.class) and CommandExecutor<OrderDomainEntity> — step transitions and domain state mutations are strictly verified by the Java compiler. Refactor fearlessly with zero untyped JSON strings and zero choreography spaghetti.
Select Integration Pattern to Switch Code & Flow:Interactive Code Explorer
Human-in-the-Loop (HITL) Wait-State: Transaction sleeps safely in Event Store awaiting 3D-Secure, OTP, or manager approval.💤 100% Threads Released
PaymentGateExecutor.java
01// 1. IN EXECUTOR: Initiate process and park transaction
02@SagaExecutor(executeFor = "payment-service", value = "paymentGateExecutor")
03public class PaymentGateExecutor implements CommandExecutor<OrderDomainEntity> {
04
05 @Override
06 public ProcessStepManager<OrderDomainEntity> doProcess(
07 ProcessContext<OrderDomainEntity> context,
08 ProcessStepManager<OrderDomainEntity> stepManager
09 ) {
10 OrderDomainEntity domainEntity = context.currentDomainEntityState();
11
12 // Initiate 3D-Secure payment session with gateway
13 PaymentSession session = gatewayClient.initiate(domainEntity.getAmount(), context.idempotencyKey());
14 domainEntity.setPaymentSessionId(session.getId());
15
16 // Parks safely in Event Store for up to 24 hours — zero threads held!
17 return stepManager
18 .success("PAYMENT_SESSION_INITIATED")
19 .asSync()
20 .pauseUntilResume(Duration.ofHours(24))
21 .resumeToNextExecutor(CapturePaymentExecutor.class);
22 }
23}
24
25// 2. IN CONTROLLER: Awaken the saga when external webhook or manager approval arrives
26@RestController
27@RequestMapping("/webhooks/payment")
28public class PaymentWebhookController {
29
30 @PostMapping
31 public ResponseEntity<Void> handleWebhook(@RequestBody PaymentWebhookDTO payload) {
32 sagaTemplate.resume(payload.getResumeKey(), Duration.ofMinutes(15))
33 .put("gatewayPaymentId", payload.getPaymentId())
34 .put("approvalStatus", payload.getStatus())
35 .execute(); // Hands context directly to CapturePaymentExecutor!
36 return ResponseEntity.ok().build();
37 }
38}

Read the Full Architectural Whitepaper

Explore the mathematical proofs, commit barrier timings, LIFO reverse autopilot, and complete pattern catalog in the official specification.

Read Whitepaper & Spec
Architectural Foundations

Domain-Centric, Natively Reactive, & Atomic.

Eliminate centralized bottlenecks. StackSaga preserves bounded contexts by embedding orchestration directly into your domain services, running on an event-driven non-blocking reactive core.

Foundational Principle 1

Domain-Centric (Embedded) Orchestration

Traditional orchestrators force you to deploy, manage, and scale heavy external servers (like Temporal or Camunda clusters). StackSaga embeds directly into standard microservices:

Zero Dedicated Orchestration Infrastructure

No separate coordinator servers to deploy, monitor, or pay for. Your service itself is the orchestrator for its own business domain.

Zero-Dependency Downstream Microservices

Participating utility services (e.g. inventory-service, payment-gateway) remain pure, standard REST or gRPC APIs. They have zero StackSaga code and zero saga awareness.

In-Process Sub-Millisecond Execution

Eliminates extra network hops between worker pollers and workflow servers. State progression occurs in-process at memory speeds.

Safe Domain-Entity Casting

During rolling Canary deployments, StackSaga's Safe Casting engine and UnknownPropertyArchive intercept removed legacy properties during down-casting—preventing deserialization crashes and eliminating data loss on rollback.

Smart Endpoints • Dumb PipesLearn more
Foundational Principle 2

The Saga Executor Pattern

Enforces the immutable rule of distributed reliability: One Executor = Exactly One Atomic Transaction Boundary. Sealed generic contracts guarantee compile-time type safety and keep your architecture spaghetti-less:

Compiler-Verified Class Transitions

Step transitions reference concrete Java classes (.toNextExecutor(ReserveInventoryExecutor.class)). Renaming or refactoring an executor is validated by the compiler, eliminating broken string references.

Command vs. Query Isolation

CommandExecutor encapsulates state-mutating actions requiring doRevert(). QueryExecutor encapsulates read-only operations with automatic rollback pruning.

Decoupled Callbacks via ResumeContext

External webhook controllers never directly mutate domain aggregates. Payloads pass through an immutable ResumeContext, ensuring only the executor interprets callback data.

Multi-Stage 1-to-Many Compensations

Enterprise rollbacks need more than an isolated undo. Executors support chaining Pre-RevertExecutor and Post-RevertExecutor lifecycles to handle pre-reversal security holds, audit logs, and customer alerts without polluting primary business logic.

Pristine State Restoration

When an executor re-executes on timeout, in-memory dirty mutations are discarded and domain state is cleanly reconstructed from the Event Store.

Spaghetti-Less • 1:N Reversals • Safe CastingView Reference
Foundational Principle 3 • Project Reactor Core

Natively Reactive & Non-Blocking Architecture

StackSaga was not retrofitted for reactivity. Under the hood, the entire Saga Execution Coordinator (SEC) operates reactively on Project Reactor. It provides complete native parity between non-blocking reactive stacks (ReactiveCommandExecutor, Spring WebFlux, Project Reactor Mono/Flux, R2DBC) and traditional blocking stacks (CommandExecutor, Spring MVC, JPA), allowing thousands of concurrent sagas to execute on minimal CPU threads with zero thread exhaustion.

Architectural Benchmark

Why Architects Choose StackSaga

Compare StackSaga's domain-centric model with dedicated workflow servers and uncoordinated event choreography.

Architectural DimensionStackSaga (Domain-Centric USM)Dedicated Clusters (Temporal / Camunda)DIY Event Choreography (Kafka Chaining)
Infrastructure Footprint
0 Dedicated Orchestrator Servers (Embedded directly in domain microservices)
Heavy Dedicated Cluster (Requires separate server nodes + database)
Broker Clusters only (Kafka/RabbitMQ), but complex ad-hoc plumbing
Concurrency & Execution Engine
Natively Reactive & Non-Blocking (Project Reactor event-loop + R2DBC)
Task Queue Long-Polling (Worker thread pools polling central server)
Message consumer thread pools per partition
Execution Latency
Sub-millisecond (In-process execution at memory speeds)
Multi-millisecond network hops (Worker polling ↔ Orchestrator server)
Broker network latency for every event transition
Type Safety & Developer Experience (DX)
100% Compile-Time Type-Safe (Spaghetti-less clean contracts: generic CommandExecutor<T>, compiler-checked .toNextExecutor(Class), IDE autocomplete, in-memory unit tests)
Partially Typed (String-bound activity registrations, untyped payload serialization boundaries, external worker poller boilerplate)
Choreography Spaghetti (Untyped JSON payloads, string-based event topics, fragmented rollback handlers scattered across 10+ repos)
Mixed-Style Pipeline (STP + HITL)
Native in 1 Pipeline (Seamlessly blends sub-ms automated STP and days-long pausable wait-states with unified reverse compensation)
Supported via External Clusters (Requires heavy server orchestration, worker polling, and manual compensation try/catches)
Fragile Anti-Pattern (Cannot safely bridge synchronous caller response with async wait-states without ad-hoc state machines & race conditions)
Pausable Wait-States & HITL
100% Worker Thread Release (Sleeps in Event Store; zero resource leakage during hours/days of waiting)
External Task Polling (Requires worker listener pools and heartbeat timeouts)
Extreme Complexity (Requires custom correlation state machines and timeout schedulers)
Downstream Service Impact
Zero Dependencies (Participating services remain pure REST/gRPC APIs)
Activity Worker Coupling (Participating services must install Temporal SDKs or require custom proxy worker wrappers)
High Coupling (Every participant must bind to specific saga topics)
Automated Reverse Compensation
Deterministic Reverse Autopilot (Automatic LIFO unwinding + Query Pruning)
Manual Compensation (Developers must write explicit reverse flow graphs)
Choreography Pinball (Prone to cyclic rollback loops and race conditions)
Multi-Stage Compensation (1-to-Many Reversals)
Native 1-to-Many Reversals (Pre-RevertExecutor + doRevert + Post-RevertExecutor for audit logs, holds & customer alerts)
Single-Activity Rollbacks (Requires complex nested sub-workflows or manual compensation error trees)
Cascading Event Sprawl (Requires fan-out rollback topics and error-prone correlation state)
Schema Evolution & Safe Casting
Zero-Data-Loss Safe Casting (UnknownPropertyArchive safely captures legacy fields during Up/Down-Casting; fail-fast boot check)
Non-Deterministic Replay Risk (Workflow.getVersion() branching required; replay crashes on unhandled class changes)
Poison-Pill Deserialization Failures (Dead-letter queue loops or silent data loss with ignoreUnknown=true)
Event Sourcing & State Storage
Zero-Infrastructure (Uses your existing MySQL, PostgreSQL, Oracle, or Cassandra)
Dedicated DB Cluster (Maintained exclusively for the orchestration engine)
No unified event store (Fragmented across independent service DBs)
Distributed Retries Without Locks
Murmur3 Token-Ring Partitioning (Conflict-free self-healing)
Worker Lease Management / Heartbeat polling
Consumer group rebalances & retry dead-letter queues

* Temporal and Camunda are trademarks of their respective owners. Comparison based on standard production architecture deployments.

Enterprise Reliability Without Complexity

Engineered for architects and developers who need bulletproof distributed consistency with minimal operational overhead.

Zero Dedicated Servers & No ESB

Ditch heavyweight external orchestration servers and legacy ESBs. StackSaga embeds directly into domain microservices ('smart endpoints, dumb pipes') with zero extra infrastructure.

Dual LRT: Continuous STP & Pausable HITL

Execute unbroken straight-through processing (STP) at sub-millisecond speeds, or pause transactions for hours or days awaiting 3D-Secure webhooks or manual KYC approvals without thread starvation.

Native Event Sourcing on Existing DBs

Persist immutable temporal transaction logs directly in your existing relational (MySQL, PostgreSQL, Oracle) or NoSQL (Cassandra, ScyllaDB) database without deploying a dedicated event store cluster.

The Saga Executor Pattern

Strictly enforces 'One Executor = One Atomic Transaction Boundary'. Typed Command and Query executors, decoupled webhook ingestion via ResumeContext, and pristine state restoration.

Zero Downstream Dependencies

Downstream utility microservices remain vanilla REST, gRPC, or GraphQL services. They require zero StackSaga code, no special SDK wrappers, and zero knowledge of the saga lifecycle.

Lock-Free Token-Ring Retries

Distributed retry agents use Murmur3 consistent hashing token-ring partitioning to coordinate conflict-free recovery for transient faults without database locking contention.

Built-in Transaction Tracing

Comprehensive visual Trace Window dashboard for monitoring and inspecting distributed transactions in real-time across execution spans, state snapshots, and compensation paths.

Natively Reactive & Non-Blocking

Built on Project Reactor from the ground up. Operates asynchronously on event-loop threads with backpressure support, eliminating thread exhaustion while seamlessly bridging to imperative Spring MVC.

The Complete Ecosystem

Everything you need for enterprise distributed transaction management in one cohesive, modular platform.

stacksaga-spring-boot-starter

Unified Orchestrator Engine (SEC)

Domain-embedded execution coordinator driving Continuous STP, Pausable HITL, Two-Stage messaging, and deterministic reverse compensation.

  • Dual LRT: Continuous STP & Pausable HITL
  • Automated reverse compensation & query pruning
  • Zero downstream utility service dependencies
stacksaga-database-support

Zero-Infrastructure Event Store

Built-in event-sourcing layer turning your primary database (MySQL, PostgreSQL, Oracle, Cassandra, ScyllaDB) into an immutable saga event store.

  • No separate event store cluster required
  • Immutable temporal audit trails
  • Pristine state restoration on retry
stacksaga-ring-coordinator

Distributed Retry Ring Coordinator

Cluster coordination service utilizing Murmur3 token ring partitioning to assign conflict-free retry ownership across active orchestrator nodes.

  • Lock-free distributed recovery
  • Zero single-point-of-failure
  • Automated rebalancing on scale-out
stacksaga-trace-window

Trace Window Observability

Dedicated operator and developer dashboard for real-time visualization of distributed saga executions, step states, and failure diagnostics.

  • Live execution graphs & step timelines
  • Data privacy: data stays inside your VPC
  • Inspection and manual operational replay
New Tool

StackSaga Initializer

Bootstrap a StackSaga project in seconds. Select your version, build tool, orchestration or coordinator type and database — then copy the exact dependencies and configuration you need, no boilerplate hunting required.

Pick your stack

Choose the StackSaga version, build tool, orchestration or coordinator type, application mode and database.

Copy the snippets

Get the ready-to-use BOM, dependencies and configuration — formatted for Maven or Gradle.

Start building

Drop the snippets into your project and you're ready to orchestrate sagas.

Built for Modern Cloud Architectures

Everything you need to orchestrate complex transactions across distributed microservices.

Spaghetti-Less, Clean & Type-Safe Architecture

Eliminate the struggle with spaghetti systems. StackSaga replaces untyped JSON message brokers with strongly-typed Java contracts (CommandExecutor<T>) and compiler-verified class transitions (.toNextExecutor(Class)) — catching workflow bugs at build time, not 2 AM in production.

Native Mixed-Style Saga (Continuous STP + Pausable HITL)

The first framework to execute mixed-style sagas in the exact same pipeline. Seamlessly chain sub-second automated Straight-Through Processing (STP) and days-long pausable Human-in-the-Loop (HITL) wait-states — with zero thread starvation, zero dedicated servers, and automatic unified reverse compensation.

1-to-Many Multi-Stage Compensations

Beyond rigid 1:1 academic rollbacks. Real enterprise microservices require multi-stage compensations (fraud verification, audit locks, partner alerts). StackSaga natively chains Pre-RevertExecutors and Post-RevertExecutors around any action without dirtying core transaction logic.

Safe Domain-Entity Casting (Zero Data Loss)

Deploy rolling updates without downtime or data corruption. StackSaga's Safe Casting engine uses UnknownPropertyArchive to safely capture deprecated or legacy attributes during Up/Down-Casting across rolling Canary pods — backed by a fail-fast startup check that prevents runtime poison pills.

Pristine State Restoration

Guarantees safe, idempotent retries by re-hydrating execution state directly from the event log, eliminating dirty state carry-over caused by uncommitted in-memory mutations.

Guaranteed Eventual Consistency

Enforces distributed consistency across microservices with automatic reverse compensation on failure, Two-Stage messaging commit barriers, and zero-dependency downstream utility services.

Ready to orchestrate your microservices?

Explore the comprehensive documentation, read the Unified Saga Model whitepaper, and bootstrap your project with StackSaga Initializer.