# scalar-labs/scalardb-saga architecture

> Architecture diagram of the GitHub repository scalar-labs/scalardb-saga, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/scalar-labs/scalardb-saga
- Repository: https://github.com/scalar-labs/scalardb-saga

## Overview

#### Purpose and deployment modes
ScalarDB Saga is a Java saga/TCC orchestration system for distributed service workflows. It persists durable state and an append-only event history through ScalarDB rather than requiring a broker. It can run embedded (including Java code steps) or as a standalone server with REST and gRPC APIs.
- `core/src/main/java/com/scalar/db/saga/engine/SagaEngine.java`
- `server/src/main/java/com/scalar/db/saga/server/SagaServer.java`
- `api/src/main/java/com/scalar/db/saga/api/SagaOrchestrator.java`

#### Public contracts and client entry points
The `api` module defines application-facing orchestration, administration, step, context, status, detail, and exception contracts. Embedded callers construct/use the default engine services; remote Java 8-compatible callers use gRPC SDK implementations. RPC schemas are the protocol boundary between client and server.
- `api/src/main/java/com/scalar/db/saga/api/SagaAdminService.java`
- `api/src/main/java/com/scalar/db/saga/api/Step.java`
- `client/src/main/java/com/scalar/db/saga/grpc/GrpcSagaOrchestratorClient.java`
- `rpc/src/main/proto/saga.proto`

#### Definition and step-resolution layer
Saga definitions are parsed from JSON/YAML, versioned/registered, and turned into executable steps. Definitions support conventional saga execution/compensation and TCC reservation/confirmation/cancellation. Steps may resolve reflectively in embedded mode or bind declarative service calls to transport adapters.
- `core/src/main/java/com/scalar/db/saga/definition/SagaDefinitionParser.java`
- `core/src/main/java/com/scalar/db/saga/engine/SagaDefinitionRegistry.java`
- `core/src/main/java/com/scalar/db/saga/engine/ReflectiveStepResolver.java`
- `core/src/main/java/com/scalar/db/saga/transport/DeclarativeBindingTccStep.java`

#### Execution, state transitions, and recovery
`SagaEngine` drives steps in order, records attempted outcomes, applies retry/timeout policy, and compensates completed work in reverse on saga failure. TCC follows reserve-before-confirm semantics; confirmation failures are recovery-driven forward progress. Recovery managers find stranded nonterminal sagas, resolve the appropriate action from durable history, and retry; retention removes old data under policy.
- `core/src/main/java/com/scalar/db/saga/engine/SagaEngine.java`
- `core/src/main/java/com/scalar/db/saga/engine/SagaRecoveryManager.java`
- `core/src/main/java/com/scalar/db/saga/engine/RecoveryActionResolver.java`
- `core/src/main/java/com/scalar/db/saga/engine/TimeoutPolicy.java`

#### Persistence boundary
The engine depends on the `SagaStore` abstraction, with `ScalarDbSagaStore` implementing durable definitions, state snapshots, events, listing, and administrative audit records via ScalarDB. The event/state model enables another replica to resume a crashed coordinator; step implementations must therefore be idempotent when execution occurred before its result was recorded.
- `core/src/main/java/com/scalar/db/saga/store/SagaStore.java`
- `core/src/main/java/com/scalar/db/saga/store/ScalarDbSagaStore.java`
- `core/src/main/java/com/scalar/db/saga/store/SagaEvent.java`
- `core/src/main/java/com/scalar/db/saga/store/SagaSchema.java`

#### Participant-service transport and asynchronous callbacks
Declarative steps issue outbound HTTP calls through a transport abstraction, classify HTTP/transport failures for retryability, interpolate/capture saga-context values, and propagate correlation. Long-running participant work can return asynchronously and resume a saga through callback handling; callback URLs are HMAC-protected in server mode.
- `core/src/main/java/com/scalar/db/saga/transport/HttpTransportAdapter.java`
- `core/src/main/java/com/scalar/db/saga/transport/OutboundHttpPolicy.java`
- `core/src/main/java/com/scalar/db/saga/transport/SagaCorrelationContext.java`
- `server/src/main/java/com/scalar/db/saga/server/api/CallbackResource.java`

#### Server edge, security, and infrastructure
The server composes the core engine, ScalarDB-backed store, REST resources, and generated gRPC services. Both transports enforce authentication/authorization and rate limiting before orchestration/admin operations. Supported security providers include API keys, JWT, or noop; deployment is a Java 21 container, while client/API/RPC artifacts target Java 8. ScalarDB connects this service to supported relational, NoSQL, or cloud database backends.
- `server/src/main/java/com/scalar/db/saga/server/SagaServerCommand.java`
- `server/src/main/java/com/scalar/db/saga/server/api/SagaResource.java`
- `server/src/main/java/com/scalar/db/saga/server/grpc/SagaServiceImpl.java`
- `server/src/main/java/com/scalar/db/saga/server/security/SagaSecurityHandler.java`
- `server/docker/Dockerfile`

Main entry points: [`core/src/main/java/com/scalar/db/saga/engine/SagaEngine.java`](https://github.com/scalar-labs/scalardb-saga/blob/main/core/src/main/java/com/scalar/db/saga/engine/SagaEngine.java) (Saga engine), [`core/src/main/java/com/scalar/db/saga/store/ScalarDbSagaStore.java`](https://github.com/scalar-labs/scalardb-saga/blob/main/core/src/main/java/com/scalar/db/saga/store/ScalarDbSagaStore.java) (ScalarDB saga store), [`core/src/main/java/com/scalar/db/saga/engine/SagaRecoveryManager.java`](https://github.com/scalar-labs/scalardb-saga/blob/main/core/src/main/java/com/scalar/db/saga/engine/SagaRecoveryManager.java) (Recovery manager), [`server/src/main/java/com/scalar/db/saga/server/SagaServer.java`](https://github.com/scalar-labs/scalardb-saga/blob/main/server/src/main/java/com/scalar/db/saga/server/SagaServer.java) (Saga server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client contracts"]
  node_api["Public API contracts<br/>Java API"]
  node_grpc_client["gRPC Java client<br/>client SDK"]
  node_rpc["Saga RPC schema<br/>protobuf<br/>[saga.proto]"]
end

subgraph group_core["Saga core"]
  node_definitions["Definition parser<br/>definition layer"]
  node_registry["Definition registry"]
  node_step_resolution["Step resolution<br/>step resolver"]
  node_engine{{"Saga engine<br/>orchestrator<br/>[SagaEngine.java]"}}
  node_recovery["Recovery manager<br/>recovery worker"]
  node_recovery_actions["Recovery action resolver<br/>recovery policy"]
  node_store[("Saga store<br/>persistence port<br/>[SagaStore.java]")]
  node_scalar_store[("ScalarDB saga store<br/>store adapter")]
  node_events["Saga event history<br/>event model<br/>[SagaEvent.java]"]
  node_transport["HTTP transport adapter<br/>participant transport"]
end

subgraph group_server["Server runtime"]
  node_server_runtime["Saga server<br/>Java 21 service<br/>[SagaServer.java]"]
  node_security["Security gateway<br/>auth and rate limiting"]
  node_rest["REST saga resource<br/>REST endpoint<br/>[SagaResource.java]"]
  node_grpc_service["gRPC saga service<br/>gRPC endpoint"]
  node_callbacks["Async callbacks<br/>callback endpoint"]
  node_container["Server container<br/>deployment image"]
end

node_participants["Participant services<br/>external services"]
node_scalardb[("ScalarDB<br/>durable data layer")]

node_grpc_client -->|"uses"| node_rpc
node_rpc -->|"generates contract"| node_grpc_service
node_api -->|"embedded orchestration"| node_engine
node_definitions -->|"parsed definitions"| node_registry
node_registry -->|"executable definition"| node_engine
node_engine -->|"resolves steps"| node_step_resolution
node_step_resolution -->|"declarative actions"| node_transport
node_transport -->|"HTTP actions"| node_participants
node_engine -->|"records state and outcomes"| node_store
node_recovery -->|"finds nonterminal sagas"| node_store
node_recovery -->|"selects next action"| node_recovery_actions
node_recovery -->|"retries or resumes"| node_engine
node_store -->|"implemented by"| node_scalar_store
node_scalar_store -->|"persists"| node_events
node_scalar_store -->|"uses"| node_scalardb
node_server_runtime -->|"composes"| node_engine
node_server_runtime -->|"composes"| node_scalar_store
node_security -->|"guards"| node_rest
node_security -->|"guards"| node_grpc_service
node_rest -->|"orchestration and admin"| node_engine
node_grpc_service -->|"orchestration and admin"| node_engine
node_callbacks -->|"resumes saga"| node_engine
node_container -->|"packages"| node_server_runtime

click node_api "https://github.com/scalar-labs/scalardb-saga/blob/main/api/src/main/java/com/scalar/db/saga/api/SagaOrchestrator.java"
click node_grpc_client "https://github.com/scalar-labs/scalardb-saga/blob/main/client/src/main/java/com/scalar/db/saga/grpc/GrpcSagaOrchestratorClient.java"
click node_rpc "https://github.com/scalar-labs/scalardb-saga/blob/main/rpc/src/main/proto/saga.proto"
click node_definitions "https://github.com/scalar-labs/scalardb-saga/blob/main/core/src/main/java/com/scalar/db/saga/definition/SagaDefinitionParser.java"
click node_registry "https://github.com/scalar-labs/scalardb-saga/blob/main/core/src/main/java/com/scalar/db/saga/engine/SagaDefinitionRegistry.java"
click node_step_resolution "https://github.com/scalar-labs/scalardb-saga/blob/main/core/src/main/java/com/scalar/db/saga/engine/ReflectiveStepResolver.java"
click node_engine "https://github.com/scalar-labs/scalardb-saga/blob/main/core/src/main/java/com/scalar/db/saga/engine/SagaEngine.java"
click node_recovery "https://github.com/scalar-labs/scalardb-saga/blob/main/core/src/main/java/com/scalar/db/saga/engine/SagaRecoveryManager.java"
click node_recovery_actions "https://github.com/scalar-labs/scalardb-saga/blob/main/core/src/main/java/com/scalar/db/saga/engine/RecoveryActionResolver.java"
click node_store "https://github.com/scalar-labs/scalardb-saga/blob/main/core/src/main/java/com/scalar/db/saga/store/SagaStore.java"
click node_scalar_store "https://github.com/scalar-labs/scalardb-saga/blob/main/core/src/main/java/com/scalar/db/saga/store/ScalarDbSagaStore.java"
click node_events "https://github.com/scalar-labs/scalardb-saga/blob/main/core/src/main/java/com/scalar/db/saga/store/SagaEvent.java"
click node_transport "https://github.com/scalar-labs/scalardb-saga/blob/main/core/src/main/java/com/scalar/db/saga/transport/HttpTransportAdapter.java"
click node_server_runtime "https://github.com/scalar-labs/scalardb-saga/blob/main/server/src/main/java/com/scalar/db/saga/server/SagaServer.java"
click node_security "https://github.com/scalar-labs/scalardb-saga/blob/main/server/src/main/java/com/scalar/db/saga/server/security/SagaSecurityHandler.java"
click node_rest "https://github.com/scalar-labs/scalardb-saga/blob/main/server/src/main/java/com/scalar/db/saga/server/api/SagaResource.java"
click node_grpc_service "https://github.com/scalar-labs/scalardb-saga/blob/main/server/src/main/java/com/scalar/db/saga/server/grpc/SagaServiceImpl.java"
click node_callbacks "https://github.com/scalar-labs/scalardb-saga/blob/main/server/src/main/java/com/scalar/db/saga/server/api/CallbackResource.java"
click node_container "https://github.com/scalar-labs/scalardb-saga/blob/main/server/docker/Dockerfile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_grpc_client,node_rpc toneBlue
class node_definitions,node_registry,node_step_resolution,node_engine,node_recovery,node_recovery_actions,node_store,node_scalar_store,node_events,node_transport toneAmber
class node_server_runtime,node_security,node_rest,node_grpc_service,node_callbacks,node_container toneMint
class node_participants,node_scalardb toneNeutral
```

## Components

### Client contracts

- [Public API contracts](https://github.com/scalar-labs/scalardb-saga/blob/main/api/src/main/java/com/scalar/db/saga/api/SagaOrchestrator.java): Java API · Orchestration, admin, step, and saga model contracts. · `api/src/main/java/com/scalar/db/saga/api/SagaOrchestrator.java`
- [gRPC Java client](https://github.com/scalar-labs/scalardb-saga/blob/main/client/src/main/java/com/scalar/db/saga/grpc/GrpcSagaOrchestratorClient.java): client SDK · `client/src/main/java/com/scalar/db/saga/grpc/GrpcSagaOrchestratorClient.java`
- [Saga RPC schema](https://github.com/scalar-labs/scalardb-saga/blob/main/rpc/src/main/proto/saga.proto): protobuf · Protocol boundary for remote clients and server. · `rpc/src/main/proto/saga.proto`

### Saga core

- [Definition parser](https://github.com/scalar-labs/scalardb-saga/blob/main/core/src/main/java/com/scalar/db/saga/definition/SagaDefinitionParser.java): definition layer · Parses JSON/YAML saga definitions. · `core/src/main/java/com/scalar/db/saga/definition/SagaDefinitionParser.java`
- [Definition registry](https://github.com/scalar-labs/scalardb-saga/blob/main/core/src/main/java/com/scalar/db/saga/engine/SagaDefinitionRegistry.java): definition registry · Versions and registers executable definitions. · `core/src/main/java/com/scalar/db/saga/engine/SagaDefinitionRegistry.java`
- [Step resolution](https://github.com/scalar-labs/scalardb-saga/blob/main/core/src/main/java/com/scalar/db/saga/engine/ReflectiveStepResolver.java): step resolver · Resolves embedded reflective and declarative TCC steps. · `core/src/main/java/com/scalar/db/saga/engine/ReflectiveStepResolver.java`
- [Saga engine](https://github.com/scalar-labs/scalardb-saga/blob/main/core/src/main/java/com/scalar/db/saga/engine/SagaEngine.java): orchestrator · Drives execution, retries, compensation, and TCC transitions. · `core/src/main/java/com/scalar/db/saga/engine/SagaEngine.java`
- [Recovery manager](https://github.com/scalar-labs/scalardb-saga/blob/main/core/src/main/java/com/scalar/db/saga/engine/SagaRecoveryManager.java): recovery worker · Resumes stranded sagas from durable history. · `core/src/main/java/com/scalar/db/saga/engine/SagaRecoveryManager.java`
- [Recovery action resolver](https://github.com/scalar-labs/scalardb-saga/blob/main/core/src/main/java/com/scalar/db/saga/engine/RecoveryActionResolver.java): recovery policy · `core/src/main/java/com/scalar/db/saga/engine/RecoveryActionResolver.java`
- [Saga store](https://github.com/scalar-labs/scalardb-saga/blob/main/core/src/main/java/com/scalar/db/saga/store/SagaStore.java): persistence port · Durable definitions, snapshots, events, listings, and audit records. · `core/src/main/java/com/scalar/db/saga/store/SagaStore.java`
- [ScalarDB saga store](https://github.com/scalar-labs/scalardb-saga/blob/main/core/src/main/java/com/scalar/db/saga/store/ScalarDbSagaStore.java): store adapter · `core/src/main/java/com/scalar/db/saga/store/ScalarDbSagaStore.java`
- [Saga event history](https://github.com/scalar-labs/scalardb-saga/blob/main/core/src/main/java/com/scalar/db/saga/store/SagaEvent.java): event model · Append-only history supports cross-replica recovery. · `core/src/main/java/com/scalar/db/saga/store/SagaEvent.java`
- [HTTP transport adapter](https://github.com/scalar-labs/scalardb-saga/blob/main/core/src/main/java/com/scalar/db/saga/transport/HttpTransportAdapter.java): participant transport · Executes declarative participant calls with failure classification. · `core/src/main/java/com/scalar/db/saga/transport/HttpTransportAdapter.java`

### Server runtime

- [Saga server](https://github.com/scalar-labs/scalardb-saga/blob/main/server/src/main/java/com/scalar/db/saga/server/SagaServer.java): Java 21 service · Composes engine, store, REST, and gRPC endpoints. · `server/src/main/java/com/scalar/db/saga/server/SagaServer.java`
- [Security gateway](https://github.com/scalar-labs/scalardb-saga/blob/main/server/src/main/java/com/scalar/db/saga/server/security/SagaSecurityHandler.java): auth and rate limiting · Enforces API key, JWT, or noop security before operations. · `server/src/main/java/com/scalar/db/saga/server/security/SagaSecurityHandler.java`
- [REST saga resource](https://github.com/scalar-labs/scalardb-saga/blob/main/server/src/main/java/com/scalar/db/saga/server/api/SagaResource.java): REST endpoint · `server/src/main/java/com/scalar/db/saga/server/api/SagaResource.java`
- [gRPC saga service](https://github.com/scalar-labs/scalardb-saga/blob/main/server/src/main/java/com/scalar/db/saga/server/grpc/SagaServiceImpl.java): gRPC endpoint · `server/src/main/java/com/scalar/db/saga/server/grpc/SagaServiceImpl.java`
- [Async callbacks](https://github.com/scalar-labs/scalardb-saga/blob/main/server/src/main/java/com/scalar/db/saga/server/api/CallbackResource.java): callback endpoint · Resumes long-running work from HMAC-protected callbacks. · `server/src/main/java/com/scalar/db/saga/server/api/CallbackResource.java`
- [Server container](https://github.com/scalar-labs/scalardb-saga/blob/main/server/docker/Dockerfile): deployment image · `server/docker/Dockerfile`

### Other components

- **Participant services**: external services · Idempotent services execute saga and TCC actions.
- **ScalarDB**: durable data layer · Connects saga storage to supported database backends.

## Connections

- gRPC Java client → Saga RPC schema: uses
- Saga RPC schema → gRPC saga service: generates contract
- Public API contracts → Saga engine: embedded orchestration
- Definition parser → Definition registry: parsed definitions
- Definition registry → Saga engine: executable definition
- Saga engine → Step resolution: resolves steps
- Step resolution → HTTP transport adapter: declarative actions
- HTTP transport adapter → Participant services: HTTP actions
- Saga engine → Saga store: records state and outcomes
- Recovery manager → Saga store: finds nonterminal sagas
- Recovery manager → Recovery action resolver: selects next action
- Recovery manager → Saga engine: retries or resumes
- Saga store → ScalarDB saga store: implemented by
- ScalarDB saga store → Saga event history: persists
- ScalarDB saga store → ScalarDB: uses
- Saga server → Saga engine: composes
- Saga server → ScalarDB saga store: composes
- Security gateway → REST saga resource: guards
- Security gateway → gRPC saga service: guards
- REST saga resource → Saga engine: orchestration and admin
- gRPC saga service → Saga engine: orchestration and admin
- Async callbacks → Saga engine: resumes saga
- Server container → Saga server: packages