# hodfords-minhngo-be/temporal-saga architecture

> Architecture diagram of the GitHub repository hodfords-minhngo-be/temporal-saga, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hodfords-minhngo-be/temporal-saga
- Repository: https://github.com/hodfords-minhngo-be/temporal-saga

## Overview

##### Main Components
- Order Microservice: This service handles order-specific logic, including endpoints (controllers), service layers, and data persistence (using PostgreSQL, as seen in the configurations and migrations).
- Order Saga Orchestrator: This service manages the distributed transaction workflows using Temporal. It is responsible for coordinating multiple steps (or activities) such as order creation, payment, and shipment, and for executing compensation actions if one of the steps fails.
- Temporal Server: Not part of the business logic per se but a core infrastructure element that runs via Docker Compose. It’s essential for the orchestration of workflows.
- External Dependencies: Redis and PostgreSQL, started via Docker Compose. They provide caching/session management and persistence, respectively.
- Docker and Deployment Scripts: The docker-compose files (for Temporal and services) indicate containerization and deployment environment.

##### Relationships and Interactions
- The Order Saga Orchestrator initiates workflows that orchestrate transactions by calling activities within the microservices like the Order Microservice.
- Communication could be via HTTP or messaging (likely using microservices communication patterns supported by NestJS) between the orchestrator and the order service.
- Both microservices use similar configuration patterns (notably NestJS is in play with controllers, modules, and service layers) and share design elements such as entities, guards, and helpers.
- Databases are accessed by both services – configuration files in both microservice directories indicate database settings, particularly the use of migrations in the Order Microservice.
- Redis and Temporal are infrastructure elements that form part of the orchestration and caching mechanisms.

##### Key Architectural Patterns and Design Principles
- The Saga Pattern for distributed transactions: Emphasize that each business transaction (workflow) is broken into local transactions with compensation capabilities.
- Microservices Architecture: Clearly separate the Order Microservice from the Order Saga Orchestrator as distinct bounded contexts.
- Containerization and Deployment: Show Docker containers (or orchestration framework) that house the Temporal Server, Redis, and PostgreSQL, as well as the service microservices.
- Use of NestJS: Although not required to show every line of code, note that the project structure’s modules (controllers, services, providers) suggest an MVC-like pattern as used by NestJS.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Infrastructure Section
    subgraph "Infrastructure"
        temporal["Temporal Server"]:::infrastructure
        redis["Redis"]:::infrastructure
        postgres["PostgreSQL"]:::infrastructure
        docker["Docker & Deployment"]:::infrastructure
    end

    %% Order Saga Orchestrator Section
    subgraph "Order Saga Orchestrator"
        orchestrator["Order Saga Orchestrator"]:::microservice
        activity["Workflow & Activities (Saga)"]:::orchestration
        temporalInt["Temporal Integration"]:::orchestration
    end

    %% Order Microservice Section
    subgraph "Order Microservice"
        microservice["Order Microservice"]:::microservice
        controllers["Controllers & HTTP Endpoints"]:::microservice
        services["Service & Repository Layers"]:::microservice
        db["Database & Migrations"]:::microservice
    end

    %% Internal interactions within Order Microservice
    controllers -->|"calls"| services
    services -->|"persists"| db

    %% Interactions between Orchestrator and Order Microservice
    activity -->|"calls"| controllers
    controllers -.->|"compensates"| activity
    orchestrator -->|"HTTP_calls"| microservice

    %% Temporal integration interactions
    temporalInt -->|"orchestrates"| temporal
    temporal -->|"responds"| temporalInt

    %% Database connection from Order Microservice to external PostgreSQL
    db -->|"stores_data"| postgres

    %% Docker deployments and external dependency spin-up
    docker -->|"deploys"| microservice
    docker -->|"deploys"| orchestrator
    docker -->|"spins_up"| temporal
    docker -->|"spins_up"| redis
    docker -->|"spins_up"| postgres

    %% Class definitions for styling
    classDef microservice fill:#bbf,stroke:#333,stroke-width:2px;
    classDef infrastructure fill:#cfc,stroke:#333,stroke-width:2px;
    classDef orchestration fill:#fcc,stroke:#333,stroke-width:2px;

    %% Click Events
    click microservice "https://github.com/hodfords-minhngo-be/temporal-saga/tree/main/sample/order-microservice"
    click controllers "https://github.com/hodfords-minhngo-be/temporal-saga/tree/main/sample/order-microservice/src/domains/orders/http"
    click services "https://github.com/hodfords-minhngo-be/temporal-saga/tree/main/sample/order-microservice/src/domains/orders/services"
    click db "https://github.com/hodfords-minhngo-be/temporal-saga/blob/main/sample/order-microservice/src/configs/database.config.ts"
    click orchestrator "https://github.com/hodfords-minhngo-be/temporal-saga/tree/main/sample/order-saga-orchestrator"
    click activity "https://github.com/hodfords-minhngo-be/temporal-saga/blob/main/sample/order-saga-orchestrator/src/domains/orders/saga/workflows/place-order/place-order.workflow.ts"
    click temporalInt "https://github.com/hodfords-minhngo-be/temporal-saga/tree/main/sample/order-saga-orchestrator/src/domains/temporal"
    click docker "https://github.com/hodfords-minhngo-be/temporal-saga/tree/main/sample/docker"
```
