Welcome to Sagaweaw

Sagaweaw is a Java library for distributed transaction orchestration with automatic compensation, intelligent retry, and real-time observability.

---

The Problem We Solve

Think of a restaurant: when you place an order, it's not just a single database insert. It's a complex flow:

1. Validate the order
2. Reserve the ingredients
3. Prepare in the kitchen
4. Charge the customer
5. Deliver

If the kitchen fails at step 3, what happens? The payment needs to be reversed, the ingredients need to go back to stock. Sagaweaw orchestrates this automatically.

---

Key Features

Feature	Description
Centralized Orchestration	Full control over the flow with a central coordinator
Automatic Compensation	Reverse-order rollback when something fails
Intelligent Retry	Configurable policies: exponential, fixed, infinite
Observability API	Query sagas, metrics, and dead letters via REST
Multi-Database	PostgreSQL, MySQL, or H2 — no extra configuration
Fluent API	Elegant, type-safe DSL
Automatic MDC	sagaId, sagaName, stepName, attempt in all logs
Micrometer / Prometheus	Duration metrics and counters published automatically
Built-in Dashboard	Real-time debug lens — timelines, dead letters, retry queue

---

30-Second Quickstart

1. Add the dependency

<dependency>
    <groupId>dev.sagaweaw</groupId>
    <artifactId>sagaweaw-spring-boot-starter</artifactId>
    <version>1.0.14</version>
</dependency>

2. Create your first Saga

@Saga("pix-payment")
public class PixPaymentSaga implements SagaDefinition<PixContext> {
    
    @Override
    public SagaFlow<PixContext> define(SagaBuilder<PixContext> saga) {
        return saga
            .step("validate-dict")
                .invoke(this::validateDict)
                .compensate(this::invalidateDict)
            
            .step("block-balance")
                .invoke(this::blockBalance)
                .compensate(this::unblockBalance)
            
            .step("transmit-to-bacen")  // PIVOT
                .invoke(this::transmitToBacen)
                .retry(exponential(3, Duration.ofSeconds(1)))
            
            .build();
    }
}

3. Fire it!

@Service
public class PaymentService {
    
    @Autowired
    private SagaManager sagaManager;
    
    public void processPayment(PixRequest request) {
        PixContext context = new PixContext(request);
        sagaManager.start(PixPaymentSaga.class, context);
    }
}

---

Status Indicators

Sagaweaw uses subtle visual indicators to communicate state:

Status	Color	Description
COMPLETED	Green (#4CAF50)	Step completed successfully
EXECUTING	Yellow (#F5A623)	Step in progress (pulsing)
COMPENSATED	Yellow (#F5A623)	Step compensated
FAILED	Red (#E53935)	Step failed

---

Next Steps

• The Problem → — Understand the restaurant analogy
• Quickstart → — Set up in 5 minutes
• Step Types → — COMPENSABLE, PIVOT, RETRIABLE
• Integrations → — Prometheus, Grafana, MDC, Micrometer
• API Reference → — Complete reference

---

Community

• GitHub: github.com/WeawLabs/sagaweaw
• Issues: Report a bug or suggestion

---

Apache 2.0 License — Open source and free for commercial use.

Used by teams building on Spring Boot

Sagaweaw is early-stage. If your team uses it in production, open an issue or start a discussion — we'd love to feature you here.