How dilsh0d/springboot-microservice-saga works
Project Type & Purpose
• This is a Java/Spring-Boot framework (library) for implementing the Saga Orchestration pattern in microservices.
• It provides annotations, auto-configuration and plumbing around Apache Kafka (event bus) and Redis (state store) so that any Spring Boot microservice can participate in distributed, fault-tolerant transactions.
File-Structure Analysis
Top-level:
• pom.xml, Maven wrapper, .github, LICENSE – standard Java library packaging
• src/main/java/uz/kassa/microservice/saga – main framework code
Key packages:
• annotation – custom annotations (@EnableSagaOrchestration, @SagaOrchestration, @SagaOrchestEventHandler, etc.)
• config – auto-configuration classes (Kafka, Redis, properties)
• gateway – SagaGateway implementation and Kafka listener
• event – common event wrapper, exception handler
• model – domain & embedded objects (SagaEntry, SagaState), converters (bytes↔POJO)
• process – reflection/metadata to scan Saga classes and orchestrate handlers
• resource – injection of resources into Saga instances
Resources:
• application.properties – defaults for Kafka/Redis
README Insights
• Describes the need for distributed transactions in microservice architectures (ACID breakage).
Microservice A → Kafka → SagaFramework → Redis (state) → Kafka → Microservice B
• Lists 7 key annotations and how they wire into Kafka producers/consumers and Redis.
Diagramming the System
a. Main Components
1. Client/API Layer (your microservice endpoints)
2. Saga Orchestration Framework (this library):
• Annotation processor & auto-configurer
• SagaGateway (producer)
• KafkaListener (consumer)
• SagaEngine (process module + repository)
3. Apache Kafka Cluster (topics for each event type)
4. Redis Cluster/Instance (Saga state repository)
5. Downstream microservices or internal service methods (OrderService, PaymentService, NotificationService)
b. Relationships & Data Flows
1. Client sends a “start saga” HTTP request → mapped to CreateOrderEvent
2. SagaGateway.send() serializes event → publishes to Kafka topic
3. KafkaListener consumes event → invokes SagaEngine
4. SagaEngine loads/creates Saga instance from Redis, dispatches to @SagaOrchestEventHandler method
5. Handler method calls domain services (orderService, sagaGateway for next event)
6. State changes persisted back to Redis via SagaRepository
7. If @SagaOrchestEnd, one final event may be produced and state deleted from Redis
8. Errors invoke @SagaOrchestException and trigger compensating events
c. Architectural Patterns & Principles
• Saga Orchestration (central coordinator)
• Event-Driven Architecture (Kafka as transport)
• Auto-Configuration / Convention-over-Configuration (Spring Boot starter)
• Repository pattern (Redis persistence)
• Reflection-based discovery (scanning @SagaOrchestration classes)
d. Technologies & Frameworks
• Java 8+, Spring Boot, Spring Kafka, Spring Data Redis
• Apache Kafka, Redis
• Maven packaging