# devswork-hub/storex-api-nestjs-orders architecture

> Architecture diagram of the GitHub repository devswork-hub/storex-api-nestjs-orders, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/devswork-hub/storex-api-nestjs-orders
- Repository: https://github.com/devswork-hub/storex-api-nestjs-orders

## Overview

##### Project type and purpose
- This is a NestJS-based backend “microservice” (monolith with microservice patterns) implementing a single Bounded Context (“Order”) with a GraphQL API.
- It follows Domain-Driven Design (DDD), Clean Architecture, CQRS, Event-Driven and Outbox patterns to handle commands, publish events, manage read models, and integrate with external systems (Kafka, RabbitMQ, mail, payments).

a. API Layer
- GraphQL Server (NestJS GraphQL module)
- Interceptors (logging, timeout) and custom error handlers
b. Application Layer
- CQRS Command Handlers and Query Handlers
- Domain Sagas/Choreography
- Event Handlers (to react to domain events)
c. Domain Layer (core)
- Aggregates, Entities, Value Objects, Domain Events
- Shared Domain Library (@storex-domain and src/shared/domain)
d. Persistence Layer – Command Side
- PostgreSQL (with Outbox table for local transactional outbox)
- TypeORM or Sequelize modules, transaction interceptor, UoW service
e. Persistence Layer – Query Side
- MongoDB (read models, projections)
- Redis (read-through cache and hot-data caching)
- Outbox-relay service or cron job that reads from Outbox table and writes to MongoDB or publishes to brokers
f. Messaging Layer
- Internal Domain Event Bus (in-memory or NestJS pub/sub adapter)
- External brokers:
– RabbitMQ module (publisher, consumer, DLQ, retry strategies)
– Kafka module (CDC events, thombstone interceptor)
g. Integrations
- Mail integration (queue, sender, processor)
- Payments integration service
h. Infrastructure & DevOps
- Docker & docker-compose files (per component: PG, Mongo, Redis, Kafka, RabbitMQ, ELK, Keycloak)
- Kubernetes manifests (.k8s folder)
- CI/CD workflows (GitHub Actions)
- Monitoring stack: ELK (Filebeat, Logstash, Elasticsearch, Kibana)

##### Relationships and data-flows
1. Client → GraphQL API
2. API → Command Handlers → Domain Model → Transaction committed in Postgres + Outbox insert
3. Outbox Relay (cron or CDC) reads Outbox → publishes Domain Events to RabbitMQ/Kafka
4. Event Consumers (in same service or external) handle events → update MongoDB read models → populate Redis cache
5. Client queries GraphQL → Query Handlers read from Redis/MongoDB
6. For long-running processes or sagas, commands emit events → other modules react (choreography)

##### Highlighted architectural patterns
- CQRS: separate Command Handlers vs. Query Handlers
- Outbox: transactional outbox in Postgres, relay to brokers
- Event-Driven / Choreography: domain events propagate changes
- DDD: modules per Bounded Context, vertical slice design
- Caching: Redis as read-through cache for high-frequency queries
- Shared libraries: core domain/common code extracted under lib/@storex-domain and src/shared

##### Essential details to capture
- Boundaries between Command/Query sides
- Location of Outbox table and relay mechanisms
- All messaging paths (internal event bus → external brokers → internal consumers)
- Integration points to mail and payment services
- Use of shared libraries for domain abstractions
- Deployment artifacts (Docker containers, Kubernetes namespaces)

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client"]:::external

    subgraph "API Layer"
        direction TB
        GraphQL["GraphQL Server"]:::api
        LoggingI["Logging Interceptor"]:::api
        TimeoutI["Timeout Interceptor"]:::api
        ExceptionH["Global Exception Handler"]:::api
        ErrorH["Custom Error Handler Service"]:::api
    end

    subgraph "Application Layer"
        direction TB
        Commands["CQRS Command Handlers"]:::app
        Queries["CQRS Query Handlers"]:::app
        Sagas["Domain Sagas & Event Handlers"]:::app
    end

    subgraph "Domain Layer"
        direction TB
        Aggregates["Aggregates, Entities, VOs, Domain Events"]:::domain
        SharedDomain["Shared Domain Library"]:::domain
    end

    subgraph "Persistence - Command Side"
        direction TB
        Postgres["PostgreSQL + Outbox"]:::persistence
        TypeORMMod["TypeORM Module & Config"]:::persistence
        UoW["Transaction Interceptor & UoW"]:::persistence
        OutboxSQL["Outbox (TypeORM)"]:::persistence
    end

    subgraph "Persistence - Query Side"
        direction TB
        Mongo["MongoDB Module"]:::persistence
        Redis["Redis Cache Module"]:::persistence
        OutboxMongo["Outbox Relay / Mongo"]:::persistence
        Projections["Read Model Projections"]:::persistence
    end

    subgraph "Messaging Layer"
        direction TB
        EventBus["Internal Event Bus"]:::messaging
        RabbitMQ["RabbitMQ Integration"]:::messaging
        Kafka["Kafka Integration"]:::messaging
    end

    subgraph "Integrations"
        direction TB
        Mail["Mail Service"]:::messaging
        Payments["Payments Service"]:::messaging
    end

    subgraph "Infrastructure & DevOps"
        direction TB
        Docker["Docker & Compose"]:::infra
        Kubernetes["Kubernetes Manifests"]:::infra
        CICD["CI/CD Workflows"]:::infra
    end

    Client -->|"GraphQL → createOrder(cmd)"| GraphQL
    GraphQL -->|applies| LoggingI
    GraphQL -->|applies| TimeoutI
    GraphQL -->|handles errors via| ExceptionH
    GraphQL -->|uses| ErrorH
    GraphQL -->|"invoke"| Commands
    GraphQL -->|"query"| Queries

    Commands -->|call| Aggregates
    Aggregates -->|persist + outbox| Postgres
    Postgres -->|writes to| OutboxSQL
    Postgres -->|transaction via| UoW
    TypeORMMod -->|configures| Postgres

    OutboxSQL -->|relay| OutboxMongo
    OutboxMongo -->|publish to| RabbitMQ
    OutboxMongo -->|publish to| Kafka

    EventBus -->|dispatch| Sagas
    Sagas -->|emit| Commands

    RabbitMQ -->|consume events| Projections
    Kafka -->|consume events| Projections
    Projections -->|write| Mongo
    Projections -->|cache| Redis

    Queries -->|readFrom| Redis
    Queries -->|fallback to| Mongo

    RabbitMQ -->|DLQ & retry| RabbitMQ
    Kafka -->|thombstone interceptor| Kafka

    RabbitMQ -->|mail events| Mail
    RabbitMQ -->|payment events| Payments

    Docker -->|deploy| Postgres
    Docker -->|deploy| Mongo
    Docker -->|deploy| Redis
    Docker -->|deploy| Kafka
    Docker -->|deploy| RabbitMQ
    Docker -->|deploy| ELK
    Docker -->|deploy| Keycloak

    Kubernetes -->|manifests in| Docker
    CICD -->|runs| Docker
    CICD -->|applies| Kubernetes

    click GraphQL "https://github.com/devswork-hub/storex-api-nestjs-orders/blob/main/src/app/api/graphql/graphql.module.ts"
    click LoggingI "https://github.com/devswork-hub/storex-api-nestjs-orders/blob/main/src/app/interceptors/logging.interceptor.ts"
    click TimeoutI "https://github.com/devswork-hub/storex-api-nestjs-orders/blob/main/src/app/interceptors/timeout.interceptor.ts"
    click ExceptionH "https://github.com/devswork-hub/storex-api-nestjs-orders/blob/main/exception.handler.ts"
    click ErrorH "https://github.com/devswork-hub/storex-api-nestjs-orders/blob/main/error-handling/error-handler.service.ts"
    click Commands "https://github.com/devswork-hub/storex-api-nestjs-orders/tree/main/src/modules/order/application/cqrs/handlers"
    click Sagas "https://github.com/devswork-hub/storex-api-nestjs-orders/tree/main/src/modules/order/application/messaging"
    click Aggregates "https://github.com/devswork-hub/storex-api-nestjs-orders/tree/main/src/modules/order/domain"
    click SharedDomain "https://github.com/devswork-hub/storex-api-nestjs-orders/tree/main/lib/@storex-domain/src/domain"
    click TypeORMMod "https://github.com/devswork-hub/storex-api-nestjs-orders/blob/main/src/app/persistence/typeorm/typeorm.module.ts"
    click UoW "https://github.com/devswork-hub/storex-api-nestjs-orders/blob/main/src/app/persistence/typeorm/typeorm-transaction.interceptor.ts"
    click OutboxSQL "https://github.com/devswork-hub/storex-api-nestjs-orders/tree/main/src/app/persistence/outbox/typeorm"
    click Mongo "https://github.com/devswork-hub/storex-api-nestjs-orders/blob/main/src/app/persistence/mongoose.module.ts"
    click Redis "https://github.com/devswork-hub/storex-api-nestjs-orders/blob/main/src/app/persistence/cache/cache.module.ts"
    click OutboxMongo "https://github.com/devswork-hub/storex-api-nestjs-orders/tree/main/src/app/persistence/outbox/mongo"
    click Projections "https://github.com/devswork-hub/storex-api-nestjs-orders/blob/main/src/modules/order/application/persistence/orders-projection.service.ts"
    click EventBus "https://github.com/devswork-hub/storex-api-nestjs-orders/blob/main/event-bus.in-memory.ts"
    click RabbitMQ "https://github.com/devswork-hub/storex-api-nestjs-orders/tree/main/src/app/messaging/rabbitmq"
    click Kafka "https://github.com/devswork-hub/storex-api-nestjs-orders/tree/main/src/app/messaging/kafka"
    click Mail "https://github.com/devswork-hub/storex-api-nestjs-orders/tree/main/src/app/integrations/mail"
    click Payments "https://github.com/devswork-hub/storex-api-nestjs-orders/blob/main/src/modules/order/application/integrations/payments.service.ts"
    click Docker "https://github.com/devswork-hub/storex-api-nestjs-orders/blob/main/docker-compose.yml"
    click Kubernetes "https://github.com/devswork-hub/storex-api-nestjs-orders/blob/main/.k8s"
    click CICD "https://github.com/devswork-hub/storex-api-nestjs-orders/tree/main/.github/workflows"
    
    classDef api fill:#bbdefb,stroke:#333,stroke-width:1px
    classDef app fill:#90caf9,stroke:#333,stroke-width:1px
    classDef domain fill:#a5d6a7,stroke:#333,stroke-width:1px
    classDef persistence fill:#ffe082,stroke:#333,stroke-width:1px
    classDef messaging fill:#ce93d8,stroke:#333,stroke-width:1px
    classDef infra fill:#eeeeee,stroke:#333,stroke-width:1px
    classDef external fill:#ffffff,stroke:#999,stroke-width:1px,stroke-dasharray: 5 5
```
