# kaoutharasma/nestjs-kafka-saga-pattern architecture

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

- Interactive diagram: https://gitdiagram.com/kaoutharasma/nestjs-kafka-saga-pattern
- Repository: https://github.com/kaoutharasma/nestjs-kafka-saga-pattern

## Overview

##### Project Type and Purpose
- This is a microservices architecture built with NestJS, implementing the Saga orchestration pattern via Apache Kafka.
- Three services (“order”, “inventory”, “payment”) each run in their own Docker container and communicate asynchronously through Kafka topics.

##### High-Level Components
a. Inventory Service
- Exposes a controller for “fetch-available-products” and “update-stock” use cases
- Uses an in-memory repository for products
- Subscribes/publishes to Kafka topics for stock checks and updates
b. Order Service (Saga Orchestrator)
- Exposes “create-order” controller and DTOs
- Implements a saga with ordered steps:
1. check-product-availability
2. authorize-payment
3. update-stock
4. confirm-order
- Coordinates the other two services via Kafka topics
c. Payment Service
- Exposes “authorize-payment” controller
- Uses in-memory payment repository
- Subscribes/publishes to payment-related Kafka topics
d. Apache Kafka Broker
- Central event bus for asynchronous messaging
- Topics might include:
– Order.Created
– Inventory.CheckStock / Inventory.StockConfirmed
– Payment.Authorize / Payment.Authorized
– Order.Confirmed / Order.Failed
e. Docker Compose
- Brings up all three NestJS services + Kafka + Zookeeper

##### Relationships and Data Flow
1. Client → Order Service (HTTP POST /orders)
2. Order Service publishes “Order.Created” to Kafka
3. Inventory Service consumes “Order.Created”, checks stock → publishes “Inventory.StockConfirmed” or “Inventory.OutOfStock”
4. Order Service saga consumes stock result; if confirmed → publishes “Payment.Authorize”
5. Payment Service consumes → processes payment → publishes “Payment.Authorized” or “Payment.Declined”
6. Saga continues: if authorized → publishes “Inventory.UpdateStock” → Inventory Service decrements stock → publishes “Inventory.StockUpdated”
7. Saga finalizes: publishes “Order.Confirmed” or handles compensation on failures

##### Architectural Patterns and Principles
- Microservices: each service is independently deployed in its own Docker container.
- Saga Orchestration: the Order Service coordinates a distributed transaction across services using events.
- Asynchronous Messaging: all inter-service calls use Kafka topics rather than direct RPC.
- Dependency Inversion: services depend on repository interfaces allowing in-memory (and later persistent) implementations.
- Single Responsibility: each service focuses on one business domain (orders, inventory, payments).

## Diagram (Mermaid)

```mermaid
graph TB
    classDef service fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef broker fill:#ffcc99,stroke:#333,stroke-width:1px
    classDef infra fill:#e0e0e0,stroke:#333,stroke-width:1px
    classDef client fill:#ccffcc,stroke:#333,stroke-width:1px

    Client["Client"]:::client

    subgraph "Docker Compose"
        direction TB
        subgraph "Order Service"
            direction TB
            OO["CreateOrderController"]:::service
            OD["CreateOrderDTO"]:::service
            OS["CreateOrderSaga"]:::service
            OPS1["place-order (step)"]:::service
            OPS2["check-product-availability (step)"]:::service
            OPS3["authorize-payment (step)"]:::service
            OPS4["update-stock (step)"]:::service
            OPS5["confirm-order (step)"]:::service
            SSI["Saga Step Interface"]:::service
            OR["OrderRepository (In-Memory)"]:::service
            OM1["AppModule (app.module.ts)"]:::service
            OM2["Bootstrap (main.ts)"]:::service
        end

        subgraph "Inventory Service"
            direction TB
            IC["FetchAvailableProductsController"]:::service
            IU["UpdateStockController"]:::service
            IR["ProductRepository (In-Memory)"]:::service
            IM1["AppModule (app.module.ts)"]:::service
            IM2["Bootstrap (main.ts)"]:::service
        end

        subgraph "Payment Service"
            direction TB
            PC["AuthorizePaymentController"]:::service
            PR["PaymentRepository (In-Memory)"]:::service
            PM1["AppModule (app.module.ts)"]:::service
            PM2["Bootstrap (main.ts)"]:::service
        end

        subgraph "Infrastructure"
            direction TB
            KAFKA["Kafka Broker"]:::broker
            ZK["Zookeeper"]:::infra
        end
    end

    %% Sequence and Data Flow
    Client -->|"1.PO S T /orders"| OO
    OO -->|"2.Order.Created"| KAFKA
    KAFKA -->|"3.Order.Created"| IC
    IC -->|"3a.Inventory.CheckStock"| KAFKA
    KAFKA -->|"4.Inventory.StockConfirmed/OutOfStock"| OS
    OS -->|"5.Payment.Authorize"| KAFKA
    KAFKA -->|"5a.Payment.Authorize"| PC
    PC -->|"5b.Payment.Authorized/Declined"| KAFKA
    KAFKA -->|"6.Inventory.UpdateStock"| IU
    IU -->|"6a.Inventory.StockUpdated"| KAFKA
    KAFKA -->|"7.Order.Confirmed/Failed"| OS

    %% Click Events - Inventory
    click IC "https://github.com/kaoutharasma/nestjs-kafka-saga-pattern/blob/main/inventory/src/usecases/fetch-availible-products/check-products-availiblity.controller.ts"
    click IU "https://github.com/kaoutharasma/nestjs-kafka-saga-pattern/blob/main/inventory/src/usecases/update-stock/update-stock.controller.ts"
    click IR "https://github.com/kaoutharasma/nestjs-kafka-saga-pattern/blob/main/inventory/src/repositories/memory/product.repository.ts"
    click IM1 "https://github.com/kaoutharasma/nestjs-kafka-saga-pattern/blob/main/inventory/src/app.module.ts"
    click IM2 "https://github.com/kaoutharasma/nestjs-kafka-saga-pattern/blob/main/inventory/src/main.ts"

    %% Click Events - Order
    click OO "https://github.com/kaoutharasma/nestjs-kafka-saga-pattern/blob/main/order/src/usecases/create-order/create-order.controller.ts"
    click OD "https://github.com/kaoutharasma/nestjs-kafka-saga-pattern/blob/main/order/src/usecases/create-order/dtos/create-order-dto.ts"
    click OS "https://github.com/kaoutharasma/nestjs-kafka-saga-pattern/blob/main/order/src/usecases/create-order/saga/create-order.saga.ts"
    click OPS1 "https://github.com/kaoutharasma/nestjs-kafka-saga-pattern/blob/main/order/src/usecases/create-order/saga/steps/place-order.step.ts"
    click OPS2 "https://github.com/kaoutharasma/nestjs-kafka-saga-pattern/blob/main/order/src/usecases/create-order/saga/steps/check-product-availibilty.step.ts"
    click OPS3 "https://github.com/kaoutharasma/nestjs-kafka-saga-pattern/blob/main/order/src/usecases/create-order/saga/steps/authorize-payment.step.ts"
    click OPS4 "https://github.com/kaoutharasma/nestjs-kafka-saga-pattern/blob/main/order/src/usecases/create-order/saga/steps/update-stock.step.ts"
    click OPS5 "https://github.com/kaoutharasma/nestjs-kafka-saga-pattern/blob/main/order/src/usecases/create-order/saga/steps/confirm-order.step.ts"
    click SSI "https://github.com/kaoutharasma/nestjs-kafka-saga-pattern/blob/main/order/src/usecases/create-order/saga/steps/step.ts"
    click OR "https://github.com/kaoutharasma/nestjs-kafka-saga-pattern/blob/main/order/src/repositories/memory/order.repository.ts"
    click OM1 "https://github.com/kaoutharasma/nestjs-kafka-saga-pattern/blob/main/order/src/app.module.ts"
    click OM2 "https://github.com/kaoutharasma/nestjs-kafka-saga-pattern/blob/main/order/src/main.ts"

    %% Click Events - Payment
    click PC "https://github.com/kaoutharasma/nestjs-kafka-saga-pattern/blob/main/payment/src/usecases/authorize-payment/authorize-payment.controller.ts"
    click PR "https://github.com/kaoutharasma/nestjs-kafka-saga-pattern/blob/main/payment/src/repositories/memory/payment.repository.ts"
    click PM1 "https://github.com/kaoutharasma/nestjs-kafka-saga-pattern/blob/main/payment/src/app.module.ts"
    click PM2 "https://github.com/kaoutharasma/nestjs-kafka-saga-pattern/blob/main/payment/src/main.ts"

    %% Click Event - Docker Compose
    click Docker Compose "docker-compose.yml"
```
