# dilsh0d/springboot-microservice-saga architecture

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

- Interactive diagram: https://gitdiagram.com/dilsh0d/springboot-microservice-saga
- Repository: https://github.com/dilsh0d/springboot-microservice-saga

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Microservice Layer
    subgraph "Client Microservice" 
        direction TB
        REST["REST Controller\n(@EnableSagaOrchestration)"]:::client
        OrderService["OrderService"]:::client
        PaymentService["PaymentService"]:::client
        NotificationService["NotificationService"]:::client
    end

    %% Saga Orchestration Framework
    subgraph "Saga Orchestration Framework" 
        direction TB
        subgraph "Annotations Package" 
            Annotations["uz.kassa.microservice.saga.annotation"]:::extension
        end
        subgraph "Auto-Configuration / Starter" 
            AutoConfig["EnableSagaOrchestrationConfig"]:::framework
            SpringAutoConfig["SpringSagaAutoConfigurer"]:::framework
            RedisCfg["RedisConfig"]:::framework
            Prop["SagaConfigProperties"]:::framework
        end
        SagaGateway["SagaGateway (Kafka Producer)"]:::framework
        SagaListener["SagaKafkaListener"]:::framework
        subgraph "Saga Engine & Metadata" 
            SagaEngine["SagaEngine\n(process & reflection)"]:::framework
            ProcessMeta["SagaClassesConfigurer\nSagaClass, SagaEventClass,..."]:::framework
        end
        SagaRepo["SagaRepository (Redis)"]:::framework
        EventWrap["Event & Exception\n(SagaEventMessage, SagaExceptionHandler)"]:::framework
        ModelDomain["Model & Converters\n(domain, embed, convertors)"]:::framework
        ResourceInject["Resource Injector\n(SagaResourceInject)"]:::framework
        AppEntrypoint["SagaApplication"]:::framework
        PropsFile["application.properties"]:::framework
    end

    %% Infrastructure
    Kafka[(Kafka Cluster\nCreateOrderEventTopic\n etc.)]:::kafka
    Redis[(Redis Cluster\nSagaStateStore)]:::redis

    %% Data Flows
    REST -->|"HTTP POST StartSaga"| SagaGateway
    SagaGateway -->|"publish JSON event"| Kafka
    Kafka -->|"consume event"| SagaListener
    SagaListener -->|"invoke"| SagaEngine
    SagaEngine -->|"load/create state"| SagaRepo
    SagaRepo -->|"GET/SET state"| Redis
    SagaEngine -->|"dispatch handler"| ProcessMeta
    ProcessMeta -->|"invoke @SagaOrchestEventHandler"| EventWrap
    EventWrap -->|"call domain services"| OrderService
    EventWrap -->|"call domain services"| PaymentService
    EventWrap -->|"call domain services"| NotificationService
    EventWrap -->|"send next event"| SagaGateway
    SagaEngine -->|"on error"| EventWrap
    EventWrap -->|"publish compensating event"| SagaGateway
    SagaEngine -->|"final end"| SagaRepo
    SagaRepo -->|"DELETE state"| Redis

    %% Scanning & Config Flow
    REST -->|"@EnableSagaOrchestration triggers"| AutoConfig
    AutoConfig -->|"configure KafkaProducerFactory\nKafkaConsumerFactory\nRedisConnectionFactory"| SpringAutoConfig

    %% Click Events
    click Annotations "https://github.com/dilsh0d/springboot-microservice-saga/tree/main/src/main/java/uz/kassa/microservice/saga/annotation"
    click AutoConfig "https://github.com/dilsh0d/springboot-microservice-saga/blob/main/src/main/java/uz/kassa/microservice/saga/config/EnableSagaOrchestrationConfig.java"
    click SpringAutoConfig "https://github.com/dilsh0d/springboot-microservice-saga/blob/main/src/main/java/uz/kassa/microservice/saga/config/SpringSagaAutoConfigurer.java"
    click RedisCfg "https://github.com/dilsh0d/springboot-microservice-saga/blob/main/src/main/java/uz/kassa/microservice/saga/config/RedisConfig.java"
    click Prop "https://github.com/dilsh0d/springboot-microservice-saga/blob/main/src/main/java/uz/kassa/microservice/saga/config/SagaConfigProperties.java"
    click SagaGateway "https://github.com/dilsh0d/springboot-microservice-saga/blob/main/src/main/java/uz/kassa/microservice/saga/gateway/SagaGateway.java"
    click SagaListener "https://github.com/dilsh0d/springboot-microservice-saga/blob/main/src/main/java/uz/kassa/microservice/saga/gateway/SagaKafkaListener.java"
    click EventWrap "https://github.com/dilsh0d/springboot-microservice-saga/tree/main/src/main/java/uz/kassa/microservice/saga/event"
    click ModelDomain "https://github.com/dilsh0d/springboot-microservice-saga/tree/main/src/main/java/uz/kassa/microservice/saga/model"
    click SagaRepo "https://github.com/dilsh0d/springboot-microservice-saga/blob/main/src/main/java/uz/kassa/microservice/saga/model/repository/SagaRepository.java"
    click ProcessMeta "https://github.com/dilsh0d/springboot-microservice-saga/tree/main/src/main/java/uz/kassa/microservice/saga/process"
    click ResourceInject "https://github.com/dilsh0d/springboot-microservice-saga/tree/main/src/main/java/uz/kassa/microservice/saga/resource"
    click AppEntrypoint "https://github.com/dilsh0d/springboot-microservice-saga/blob/main/src/main/java/uz/kassa/microservice/saga/SagaApplication.java"
    click PropsFile "https://github.com/dilsh0d/springboot-microservice-saga/blob/main/src/main/resources/application.properties"

    %% Styles
    classDef client fill:#D0E6FF,stroke:#0066CC,color:#003366
    classDef framework fill:#E6FFE6,stroke:#00CC00,color:#006600
    classDef kafka fill:#FFE6CC,stroke:#FF6600,color:#993300
    classDef redis fill:#E8E6FF,stroke:#6633CC,color:#330099
    classDef extension stroke-dasharray: 5 5, fill:#F2F2F2,stroke:#999999,color:#666666
    class Annotations extension
    class AutoConfig,SpringAutoConfig,RedisCfg,Prop framework
    class SagaGateway,SagaListener,SagaEngine,ProcessMeta,SagaRepo,EventWrap,ModelDomain,ResourceInject,AppEntrypoint,PropsFile framework
```
