Architecture

Trama exposes an API for definition management and execution triggers, then processes saga executions asynchronously via queue-backed workers.

Core Components

• Application: REST endpoints and runtime bootstrap.
• RuntimeBootstrap: wires queue, consumer, processor, store, and observability.
• SagaExecutionProcessor: worker orchestration, ack/retry control, and rate-limit integration.
• DefaultSagaExecutor: step execution, retry policy decisions, compensation transitions.
• SagaExecutionStore: persistence abstraction (Redis/Postgres backing).

Execution Lifecycle

1. Definition is validated and stored (or provided inline).
2. Execution request enqueues a saga payload.
3. Consumer claims ready messages and hands them to workers.
4. Executor runs steps, persists outcomes, and either: succeeds, fails terminally, or reenqueues for retry/compensation.
5. Metrics and traces are emitted throughout all stages.

Mermaid Diagram

flowchart TB

classDef api fill:#1e293b,stroke:#60a5fa,stroke-width:2px,color:#e5e7eb;
classDef runtime fill:#1e293b,stroke:#4ade80,stroke-width:2px,color:#e5e7eb;
classDef infra fill:#1e293b,stroke:#f59e0b,stroke-width:2px,color:#e5e7eb;
classDef obs fill:#1e293b,stroke:#c084fc,stroke-width:2px,color:#e5e7eb;
classDef external fill:#1e293b,stroke:#fb7185,stroke-width:2px,color:#e5e7eb;

C[Client]:::api

subgraph Trama
direction TB

A[Ktor API]:::api

Q[Redis Queue]:::infra
P[Saga Processor]:::runtime
E[Saga Executor]:::runtime
ST[Postgres Store]:::infra

M[Prometheus Metrics]:::obs
T[OpenTelemetry Traces]:::obs

end

S[External Services]:::external

C --> A
A --> Q
Q --> P
P --> E
E --> S
E --> ST

P -.-> M
E -.-> T