stacksaga-kafka-spring-boot-starter

stacksaga-kafka-spring-boot-starter is the core dependency of the Stacksaga-Kafka Framework. it provides the essential functionalities and specifications to create and manage sagas using Kafka as the messaging backbone and ot works as Saga Execution coordinator(SEC). the dependency can be added to your Spring Boot application (the target orchestrator service) as follows,

It has been built internally using reactive programming principles, ensuring high scalability and performance. Even though the framework operates reactively under the hood, it fully supports both reactive and non-reactive (imperative) application models. 
<dependency>
    <groupId>org.stacksaga</groupId>
    <artifactId>stacksaga-kafka-spring-boot-starter</artifactId>
    <version>${latest-version}</version>
</dependency>
Make sure to add the one of database-support modules as well to enable event sourcing capabilities. because stacksaga-kafka-spring-boot-starter only provides the core saga orchestration functionalities. the event sourcing capabilities are handled by the stacksaga-database-support module. you can find more details about the database-support modules in here.
stacksaga-kafka-spring-boot-starter comes with the stacksaga-kafka-client dependency transitively. so you don’t have to add the stacksaga-kafka-client dependency separately to your target services.

What does stacksaga-kafka-spring-boot-starter do?

In high-level,
After adding the stacksaga-kafka-spring-boot-starter dependency to your Spring Boot application, it automatically configures the necessary beans and components required for saga orchestration using Kafka. and you can provide configure your saga workflows accordingly the stacksaga-kafka specifications. once the transaction is initiated, the starter module(SEC) takes care of managing the saga’s lifecycle, coordinating between different microservices, and ensuring that all steps are executed in the correct order. it also handles failures by triggering compensating actions as configured. while each execution it manages the state of the transaction and persists events to the configured event store for future-retrying, and traceability.

See the stacksaga framework architecture section to get more details about how the stacksaga-kafka-spring-boot-starter works in the overall architecture.

Related Topics

The following topics are discussed in-detailed regarding the functionalities and specifications provided by the stacksaga-kafka-spring-boot-starter module.

Customizations and Configurations

Reply Message Listener Configurations and Customizations

By default, Stacksaga Kafka Orchestrator maps all aggregator reply topics to a shared message listener container. For example, if your application has two saga domains such as process-order and process-cancel-order, the framework creates one reply topic per domain (based on the value provided in the @Aggregator annotation) and attaches both topics to the same default listener. As a result, replies from those topics are consumed by a common listener unless you override the behavior.

To customize the message listener for specific topic, update the attributes of the @SagaEventManager annotation on your custom EventManager class that extends AbstractEventManager. This allows you to define isolated listeners for specific domain.

@SagaEventManager(
        domainRootTopicSuffix = "tc4_po",
        (1)
        listenerScope = ListenerScope.ISOLATED, // create a dedicated listener for this topic.
        (2)
        concurrency = 1, // consumer concurrency for this listener (optional, default: 1)
        value = "TC4PlaceOrderEventManager"
)
public class PlaceOrderEventManager1 extends AbstractEventManager<PlaceOrderAggregator,PlaceOrderTopic> {
 //...
}
1 Setting listenerScope to ISOLATED creates a dedicated listener container for the target response topic. This is useful when you need stronger isolation, independent scaling, or domain-specific processing controls.
2 concurrency defines how many consumer threads are assigned to the listener container. The default value is 1, which preserves sequential consumption per assigned partition. Increasing this value enables parallel consumption and can improve throughput, depending on topic partitioning.
If a topic has only one partition, setting concurrency > 1 does not increase true parallelism for that partition and can introduce perceived ordering issues at the processing layer. For multi-partition topics, higher concurrency allows parallel processing across partitions, which improves throughput but may produce out-of-order handling at the aggregate/business level if your partition key strategy is incorrect. Choose concurrency based on your domain ordering guarantees and Kafka partitioning design.