# jcsalerno/microsservicos-padrao-saga-orquestrado architecture

> Architecture diagram of the GitHub repository jcsalerno/microsservicos-padrao-saga-orquestrado, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jcsalerno/microsservicos-padrao-saga-orquestrado
- Repository: https://github.com/jcsalerno/microsservicos-padrao-saga-orquestrado

## Overview

##### Project Type and Purpose
- This is a distributed microservices system implementing the Saga orchestration pattern in Spring Boot. Its goal is to manage a business transaction (creating an order, validating products, processing payment, updating inventory) across five independent services, using Apache Kafka for async messaging and Docker for containerized deployment.

##### File Structure Analysis
- Top-level services:
- order-service (Spring Boot + MongoDB)
- orchestrator-service (Spring Boot, no DB, central saga orchestrator)
- product-validation-service (Spring Boot + PostgreSQL)
- payment-service (Spring Boot + PostgreSQL)
- inventory-service (Spring Boot + PostgreSQL)
- Each service contains:
- config (exception handlers, KafkaConfig)
- core (consumer/producer, DTOs, model/repository, service logic)
- application entrypoint (…Application.java)
- Dockerfile and Gradle wrapper
- Top-level orchestration: docker-compose.yml to spin up Kafka, databases, and all services.

##### Key Architectural Insights (from README)
- Central Orchestrator coordinates the saga, sending commands to each service in sequence via Kafka topics.
- Each service listens for its topic (consumer), executes its local transaction, then emits an “event” (producer) indicating SUCCESS or FAILURE.
- The orchestrator listens to those events to decide next steps or compensate on failures.
- Databases are per-service (MongoDB for orders; PostgreSQL instances for validation, payment, inventory).

a. Main Components
- Message Broker: Apache Kafka cluster (topics for commands/events)
- Databases: MongoDB, 3× PostgreSQL
- Docker Compose / Container Host layer (optional outer boundary)
b. Relationships & Interactions
- Order Service → publishes “StartSaga” event on Kafka topic
- Orchestrator Service → consumes “StartSaga”, issues “ValidateProduct” command → Kafka
- Product-Validation Service → consumes “ValidateProduct”, writes to Postgres, publishes “ProductValidated” → Kafka
- Orchestrator → consumes “ProductValidated”, issues “ProcessPayment” → Kafka
- Payment Service → consumes “ProcessPayment”, updates Postgres, emits “PaymentProcessed” → Kafka
- Orchestrator → … issues “UpdateInventory” → Kafka → Inventory Service → Postgres → emits “InventoryUpdated” → Kafka
- Orchestrator → emits “SagaCompleted” → consumed by Order Service → writes to MongoDB
- On any failure event, orchestrator issues compensating commands in reverse order.
c. Architectural Patterns
- Saga Orchestration pattern (central coordinator)
- Pub/Sub event-driven choreography under the hood but orchestrated by a dedicated service
- Database-per-service (bounded contexts)
- Containerized microservices via Docker Compose
d. Technologies & Frameworks
- Spring Boot (Java 17+) for services
- Apache Kafka (topics, producers, consumers)
- MongoDB (Order Service)
- PostgreSQL (Validation, Payment, Inventory)
- Docker & Docker Compose

##### Detailed Element Checklist
- Component labels: service name, technology, database

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Docker Compose"
        direction TB

        %% Message Broker
        Kafka["Apache Kafka<br/>Broker"]:::kafka

        %% Databases
        MongoDB["MongoDB<br/>Orders DB"]:::db
        PostgresPV["PostgreSQL<br/>Validation DB"]:::db
        PostgresPay["PostgreSQL<br/>Payment DB"]:::db
        PostgresInv["PostgreSQL<br/>Inventory DB"]:::db

        %% Services
        subgraph "Order Service" 
            direction TB
            OSApp["OrderServiceApplication"]:::service
            OSConfig["KafkaConfig"]:::service
            OSConsumer["EventConsumer"]:::service
            OSProducer["SagaProducer"]:::service
            OSController["OderController"]:::service
        end

        subgraph "Orchestrator Service"
            direction TB
            ORApp["OrchestratorServiceApplication"]:::service
            ORConfig["KafkaConfig"]:::service
            ORConsumer["SagaOrchestratorConsumer"]:::service
            ORProducer["SagaOrchestratorProducer"]:::service
            SagaExec["SagaExecutionController"]:::service
            SagaHandler["SagaHandler"]:::service
        end

        subgraph "Product Validation Service"
            direction TB
            PVApp["ProductValidationServiceApplication"]:::service
            PVConfig["KafkaConfig"]:::service
            PVConsumer["ProductValidationConsumer"]:::service
            PVProducer["KafkaProducer"]:::service
            PVService["ProductValidationService"]:::service
        end

        subgraph "Payment Service"
            direction TB
            PSApp["PaymentServiceApplication"]:::service
            PSConfig["KafkaConfig"]:::service
            PSConsumer["PaymentConsumer"]:::service
            PSProducer["KafkaProducer"]:::service
            PSService["PaymentService"]:::service
        end

        subgraph "Inventory Service"
            direction TB
            ISApp["InventoryServiceApplication"]:::service
            ISConfig["KafkaConfig"]:::service
            ISConsumer["InventoryConsumer"]:::service
            ISProducer["KafkaProducer"]:::service
            ISService["InventoryService"]:::service
        end

    end

    %% Saga Flow (happy path)
    OSController -->|1. StartSaga| Kafka
    Kafka -->|2. Consume StartSaga| ORConsumer
    ORConsumer -->|3. ValidateProduct| Kafka
    Kafka -->|4. Consume ValidateProduct| PVConsumer
    PVConsumer -->|5. ProductValidated| Kafka
    Kafka -->|6. Consume ProductValidated| ORConsumer
    ORConsumer -->|7. ProcessPayment| Kafka
    Kafka -->|8. Consume ProcessPayment| PSConsumer
    PSConsumer -->|9. PaymentProcessed| Kafka
    Kafka -->|10. Consume PaymentProcessed| ORConsumer
    ORConsumer -->|11. UpdateInventory| Kafka
    Kafka -->|12. Consume UpdateInventory| ISConsumer
    ISConsumer -->|13. InventoryUpdated| Kafka
    Kafka -->|14. Consume InventoryUpdated| ORConsumer
    ORConsumer -->|15. SagaCompleted| Kafka
    Kafka -->|16. Consume SagaCompleted| OSConsumer
    OSConsumer -->|17. Write Order| MongoDB

    %% Click Events
    click OSApp "https://github.com/jcsalerno/microsservicos-padrao-saga-orquestrado/blob/main/order-service/src/main/java/br/com/microservices/orchestrated/orderservice/OrderServiceApplication.java"
    click OSConfig "https://github.com/jcsalerno/microsservicos-padrao-saga-orquestrado/blob/main/order-service/src/main/java/br/com/microservices/orchestrated/orderservice/config/kafka/KafkaConfig.java"
    click OSConsumer "https://github.com/jcsalerno/microsservicos-padrao-saga-orquestrado/blob/main/order-service/src/main/java/br/com/microservices/orchestrated/orderservice/core/consumer/EventConsumer.java"
    click OSProducer "https://github.com/jcsalerno/microsservicos-padrao-saga-orquestrado/blob/main/order-service/src/main/java/br/com/microservices/orchestrated/orderservice/core/producer/SagaProducer.java"
    click OSController "https://github.com/jcsalerno/microsservicos-padrao-saga-orquestrado/blob/main/order-service/src/main/java/br/com/microservices/orchestrated/orderservice/core/controller/OderController.java"

    click ORApp "https://github.com/jcsalerno/microsservicos-padrao-saga-orquestrado/blob/main/orchestrator-service/src/main/java/br/com/microservices/orchestrated/orchestratorservice/OrchestratorServiceApplication.java"
    click ORConfig "https://github.com/jcsalerno/microsservicos-padrao-saga-orquestrado/blob/main/orchestrator-service/src/main/java/br/com/microservices/orchestrated/orchestratorservice/config/kafka/KafkaConfig.java"
    click ORConsumer "https://github.com/jcsalerno/microsservicos-padrao-saga-orquestrado/blob/main/orchestrator-service/src/main/java/br/com/microservices/orchestrated/orchestratorservice/core/consumer/SagaOrchestratorConsumer.java"
    click ORProducer "https://github.com/jcsalerno/microsservicos-padrao-saga-orquestrado/blob/main/orchestrator-service/src/main/java/br/com/microservices/orchestrated/orchestratorservice/core/producer/SagaOrchestratorProducer.java"
    click SagaExec "https://github.com/jcsalerno/microsservicos-padrao-saga-orquestrado/blob/main/orchestrator-service/src/main/java/br/com/microservices/orchestrated/orchestratorservice/core/saga/SagaExecutionController.java"
    click SagaHandler "https://github.com/jcsalerno/microsservicos-padrao-saga-orquestrado/blob/main/orchestrator-service/src/main/java/br/com/microservices/orchestrated/orchestratorservice/core/saga/SagaHandler.java"

    click PVApp "https://github.com/jcsalerno/microsservicos-padrao-saga-orquestrado/blob/main/product-validation-service/src/main/java/br/com/microservices/orchestrated/productvalidationservice/ProductValidationServiceApplication.java"
    click PVConfig "https://github.com/jcsalerno/microsservicos-padrao-saga-orquestrado/blob/main/product-validation-service/src/main/java/br/com/microservices/orchestrated/productvalidationservice/config/kafka/KafkaConfig.java"
    click PVConsumer "https://github.com/jcsalerno/microsservicos-padrao-saga-orquestrado/blob/main/product-validation-service/src/main/java/br/com/microservices/orchestrated/productvalidationservice/core/consumer/ProductValidationConsumer.java"
    click PVProducer "https://github.com/jcsalerno/microsservicos-padrao-saga-orquestrado/blob/main/product-validation-service/src/main/java/br/com/microservices/orchestrated/productvalidationservice/core/producer/KafkaProducer.java"
    click PVService "https://github.com/jcsalerno/microsservicos-padrao-saga-orquestrado/blob/main/product-validation-service/src/main/java/br/com/microservices/orchestrated/productvalidationservice/core/service/ProductValidationService.java"

    click PSApp "https://github.com/jcsalerno/microsservicos-padrao-saga-orquestrado/blob/main/payment-service/src/main/java/br/com/microservices/orchestrated/paymentservice/PaymentServiceApplication.java"
    click PSConfig "https://github.com/jcsalerno/microsservicos-padrao-saga-orquestrado/blob/main/payment-service/src/main/java/br/com/microservices/orchestrated/paymentservice/config/kafka/KafkaConfig.java"
    click PSConsumer "https://github.com/jcsalerno/microsservicos-padrao-saga-orquestrado/blob/main/payment-service/src/main/java/br/com/microservices/orchestrated/paymentservice/core/consumer/PaymentConsumer.java"
    click PSProducer "https://github.com/jcsalerno/microsservicos-padrao-saga-orquestrado/blob/main/payment-service/src/main/java/br/com/microservices/orchestrated/paymentservice/core/producer/KafkaProducer.java"
    click PSService "https://github.com/jcsalerno/microsservicos-padrao-saga-orquestrado/blob/main/payment-service/src/main/java/br/com/microservices/orchestrated/paymentservice/core/service/PaymentService.java"

    click ISApp "https://github.com/jcsalerno/microsservicos-padrao-saga-orquestrado/blob/main/inventory-service/src/main/java/br/com/microservices/orchestrated/inventoryservice/InventoryServiceApplication.java"
    click ISConfig "https://github.com/jcsalerno/microsservicos-padrao-saga-orquestrado/blob/main/inventory-service/src/main/java/br/com/microservices/orchestrated/inventoryservice/config/kafka/KafkaConfig.java"
    click ISConsumer "https://github.com/jcsalerno/microsservicos-padrao-saga-orquestrado/blob/main/inventory-service/src/main/java/br/com/microservices/orchestrated/inventoryservice/core/consumer/InventoryConsumer.java"
    click ISProducer "https://github.com/jcsalerno/microsservicos-padrao-saga-orquestrado/blob/main/inventory-service/src/main/java/br/com/microservices/orchestrated/inventoryservice/core/producer/KafkaProducer.java"
    click ISService "https://github.com/jcsalerno/microsservicos-padrao-saga-orquestrado/blob/main/inventory-service/src/main/java/br/com/microservices/orchestrated/inventoryservice/core/service/InventoryService.java"

    %% Styles
    classDef service fill:#cce5ff,stroke:#004085,color:#004085;
    classDef kafka fill:#ffe5b4,stroke:#ff8c00,color:#ff8c00;
    classDef db fill:#e2e3e5,stroke:#d6d8db,color:#383d41;

    %% Link Styles for success path
    linkStyle 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16 stroke:#28a745,stroke-width:2px;
```
