# turynx/flash-sale-inventory-engine architecture

> Architecture diagram of the GitHub repository turynx/flash-sale-inventory-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/turynx/flash-sale-inventory-engine
- Repository: https://github.com/turynx/flash-sale-inventory-engine

## Overview

Flash Sale Inventory Engine is a NestJS backend for user authentication, product catalog management, inventory reservation, and Stripe checkout. The main flow is: users authenticate, browse products, reserve stock, receive a checkout URL, and complete an order through a verified Stripe webhook; reservation expiry is handled in the background. PostgreSQL-backed repositories and a Redis/BullMQ reservation subsystem support these capabilities. The graph follows documented routes and module wiring; some use-case-to-storage or payment calls are not visible in the sampled excerpts, so those links are omitted or marked unverified.

Main entry points: [`src/order/infrastructure/controllers/order.controller.ts`](https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/order/infrastructure/controllers/order.controller.ts) (Order API), [`src/product/infrastructure/controllers/product.controller.ts`](https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/product/infrastructure/controllers/product.controller.ts) (Product API), [`src/app.module.ts`](https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/app.module.ts) (Application setup), [`src/auth/infrastructure/controllers/auth.controller.ts`](https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/auth/infrastructure/controllers/auth.controller.ts) (Auth API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and identity"]
  node_app["Application setup<br/>[app.module.ts]"]
  node_auth_api["Auth API<br/>[auth.controller.ts]"]
  node_auth_cases["Auth use cases"]
  node_auth_repo["Auth repository<br/>[db.repository.ts]"]
  node_jwt["JWT guard<br/>[jwt-auth.guard.ts]"]
end

subgraph group_catalog["Product catalog"]
  node_product_api["Product API"]
  node_product_cases["Product use cases"]
  node_product_repo["Product repository<br/>[db.repository.ts]"]
end

subgraph group_orders["Orders and inventory"]
  node_order_api["Order API"]
  node_reserve_case["Reservation use case"]
  node_checkout_case["Checkout use case"]
  node_stripe_url_case["Checkout URL use case"]
  node_order_repo["Order repository<br/>[db.repository.ts]"]
  node_inventory_adapter["Redis inventory adapter"]
  node_expiry_worker["Expiry worker"]
  node_ledger_case["Ledger use case"]
  node_ledger_repo["Ledger repository"]
end

subgraph group_infra["Persistence and integrations"]
  node_postgres[("PostgreSQL")]
  node_redis["Redis and queue"]
  node_stripe["Stripe"]
  node_stripe_service["Stripe service<br/>[payment.service.ts]"]
end

node_customer(("Client"))

node_customer -->|"registers or logs in"| node_auth_api
node_auth_api -->|"executes"| node_auth_cases
node_app -->|"loads module"| node_auth_api
node_app -->|"loads module"| node_product_api
node_app -->|"loads module"| node_order_api
node_app -->|"loads module"| node_ledger_case
node_customer -->|"browses catalog"| node_product_api
node_product_api -->|"executes"| node_product_cases
node_product_api -->|"guards creation"| node_jwt
node_customer -->|"places order"| node_order_api
node_order_api -->|"guards routes"| node_jwt
node_order_api -->|"executes"| node_reserve_case
node_order_api -->|"executes"| node_stripe_url_case
node_order_api -->|"executes webhook"| node_checkout_case
node_order_api -->|"verifies webhook"| node_stripe
node_order_api -->|"configures provider"| node_order_repo
node_order_api -->|"configures provider"| node_inventory_adapter
node_order_api -->|"registers worker"| node_expiry_worker
node_order_api -->|"configures provider"| node_stripe_service
node_order_api -->|"configures provider"| node_ledger_repo
node_product_api -->|"configures provider"| node_product_repo
node_auth_api -->|"configures provider"| node_auth_repo
node_ledger_case -->|"configures provider"| node_ledger_repo
node_product_repo -->|"queries"| node_postgres
node_order_repo -->|"queries"| node_postgres
node_ledger_repo -->|"queries"| node_postgres
node_auth_repo -.->|"persists users"| node_postgres
node_inventory_adapter -.->|"uses inventory queue"| node_redis
node_expiry_worker -.->|"processes delayed jobs"| node_redis
node_stripe_service -->|"creates checkout session"| node_stripe
node_stripe_url_case -.->|"requests checkout"| node_stripe_service

click node_app "https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/app.module.ts"
click node_auth_api "https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/auth/infrastructure/controllers/auth.controller.ts"
click node_auth_cases "https://github.com/turynx/flash-sale-inventory-engine/tree/master/src/auth/application/use-cases"
click node_auth_repo "https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/auth/infrastructure/repository/db.repository.ts"
click node_jwt "https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/auth/infrastructure/guards/jwt-auth.guard.ts"
click node_product_api "https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/product/infrastructure/controllers/product.controller.ts"
click node_product_cases "https://github.com/turynx/flash-sale-inventory-engine/tree/master/src/product/application/use-cases"
click node_product_repo "https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/product/infrastructure/repository/db.repository.ts"
click node_order_api "https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/order/infrastructure/controllers/order.controller.ts"
click node_reserve_case "https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/order/application/use-cases/reserve.use-case.ts"
click node_checkout_case "https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/order/application/use-cases/checkout-order.use-case.ts"
click node_stripe_url_case "https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/order/application/use-cases/generate-stripe-url.use-case.ts"
click node_order_repo "https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/order/infrastructure/repository/db.repository.ts"
click node_inventory_adapter "https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/order/infrastructure/services/redis-inventory.adapter.ts"
click node_expiry_worker "https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/order/infrastructure/worker/reservation-expired.worker.ts"
click node_ledger_case "https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/inventory-ledger/application/use-cases/create.inventory-ledger.use-case.ts"
click node_ledger_repo "https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/inventory-ledger/infrastructure/repositories/inventory-ledger.repository.ts"
click node_stripe_service "https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/payment/payment.service.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_auth_api,node_auth_cases,node_auth_repo,node_jwt,node_customer toneBlue
class node_product_api,node_product_cases,node_product_repo toneAmber
class node_order_api,node_reserve_case,node_checkout_case,node_stripe_url_case,node_order_repo,node_inventory_adapter,node_expiry_worker,node_ledger_case,node_ledger_repo toneMint
class node_postgres,node_redis,node_stripe,node_stripe_service toneRose
```

## Components

### API and identity

- [Application setup](https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/app.module.ts): `src/app.module.ts`
- [Auth API](https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/auth/infrastructure/controllers/auth.controller.ts): `src/auth/infrastructure/controllers/auth.controller.ts`
- [Auth use cases](https://github.com/turynx/flash-sale-inventory-engine/tree/master/src/auth/application/use-cases): `src/auth/application/use-cases`
- [Auth repository](https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/auth/infrastructure/repository/db.repository.ts): `src/auth/infrastructure/repository/db.repository.ts`
- [JWT guard](https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/auth/infrastructure/guards/jwt-auth.guard.ts): `src/auth/infrastructure/guards/jwt-auth.guard.ts`

### Product catalog

- [Product API](https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/product/infrastructure/controllers/product.controller.ts): `src/product/infrastructure/controllers/product.controller.ts`
- [Product use cases](https://github.com/turynx/flash-sale-inventory-engine/tree/master/src/product/application/use-cases): `src/product/application/use-cases`
- [Product repository](https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/product/infrastructure/repository/db.repository.ts): `src/product/infrastructure/repository/db.repository.ts`

### Orders and inventory

- [Order API](https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/order/infrastructure/controllers/order.controller.ts): `src/order/infrastructure/controllers/order.controller.ts`
- [Reservation use case](https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/order/application/use-cases/reserve.use-case.ts): `src/order/application/use-cases/reserve.use-case.ts`
- [Checkout use case](https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/order/application/use-cases/checkout-order.use-case.ts): `src/order/application/use-cases/checkout-order.use-case.ts`
- [Checkout URL use case](https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/order/application/use-cases/generate-stripe-url.use-case.ts): `src/order/application/use-cases/generate-stripe-url.use-case.ts`
- [Order repository](https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/order/infrastructure/repository/db.repository.ts): `src/order/infrastructure/repository/db.repository.ts`
- [Redis inventory adapter](https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/order/infrastructure/services/redis-inventory.adapter.ts): `src/order/infrastructure/services/redis-inventory.adapter.ts`
- [Expiry worker](https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/order/infrastructure/worker/reservation-expired.worker.ts): `src/order/infrastructure/worker/reservation-expired.worker.ts`
- [Ledger use case](https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/inventory-ledger/application/use-cases/create.inventory-ledger.use-case.ts): `src/inventory-ledger/application/use-cases/create.inventory-ledger.use-case.ts`
- [Ledger repository](https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/inventory-ledger/infrastructure/repositories/inventory-ledger.repository.ts): `src/inventory-ledger/infrastructure/repositories/inventory-ledger.repository.ts`

### Persistence and integrations

- **PostgreSQL**
- **Redis and queue**
- **Stripe**
- [Stripe service](https://github.com/turynx/flash-sale-inventory-engine/blob/master/src/payment/payment.service.ts): `src/payment/payment.service.ts`

### Other components

- **Client**

## Connections

- Client → Auth API: registers or logs in (evidence: `README.md`)
- Auth API → Auth use cases: executes (evidence: `src/auth/infrastructure/controllers/auth.controller.ts`)
- Application setup → Auth API: loads module (evidence: `src/app.module.ts`)
- Application setup → Product API: loads module (evidence: `src/app.module.ts`)
- Application setup → Order API: loads module (evidence: `src/app.module.ts`)
- Application setup → Ledger use case: loads module (evidence: `src/app.module.ts`)
- Client → Product API: browses catalog (evidence: `README.md`)
- Product API → Product use cases: executes (evidence: `src/product/infrastructure/controllers/product.controller.ts`)
- Product API → JWT guard: guards creation (evidence: `src/product/infrastructure/controllers/product.controller.ts`)
- Client → Order API: places order (evidence: `README.md`)
- Order API → JWT guard: guards routes (evidence: `src/order/infrastructure/controllers/order.controller.ts`)
- Order API → Reservation use case: executes (evidence: `src/order/infrastructure/controllers/order.controller.ts`)
- Order API → Checkout URL use case: executes (evidence: `src/order/infrastructure/controllers/order.controller.ts`)
- Order API → Checkout use case: executes webhook (evidence: `src/order/infrastructure/controllers/order.controller.ts`)
- Order API → Stripe: verifies webhook (evidence: `src/order/infrastructure/controllers/order.controller.ts`)
- Order API → Order repository: configures provider (evidence: `src/order/order.module.ts`)
- Order API → Redis inventory adapter: configures provider (evidence: `src/order/order.module.ts`)
- Order API → Expiry worker: registers worker (evidence: `src/order/order.module.ts`)
- Order API → Stripe service: configures provider
- Order API → Ledger repository: configures provider
- Product API → Product repository: configures provider (evidence: `src/product/product.module.ts`)
- Auth API → Auth repository: configures provider (evidence: `src/auth/auth.module.ts`)
- Ledger use case → Ledger repository: configures provider (evidence: `src/inventory-ledger/inventory-ledger.module.ts`)
- Product repository → PostgreSQL: queries (evidence: `src/product/infrastructure/repository/db.repository.ts`)
- Order repository → PostgreSQL: queries (evidence: `src/order/infrastructure/repository/db.repository.ts`)
- Ledger repository → PostgreSQL: queries (evidence: `src/inventory-ledger/infrastructure/repositories/inventory-ledger.repository.ts`)
- Auth repository → PostgreSQL: persists users
- Redis inventory adapter → Redis and queue: uses inventory queue
- Expiry worker → Redis and queue: processes delayed jobs
- Stripe service → Stripe: creates checkout session (evidence: `src/payment/payment.service.ts`)
- Checkout URL use case → Stripe service: requests checkout
