# vernardtan/flash-sale architecture

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

- Interactive diagram: https://gitdiagram.com/vernardtan/flash-sale
- Repository: https://github.com/vernardtan/flash-sale

## Overview

Flash Sale System combines a React storefront with a NestJS API. The user browses sale status and products, creates a checkout, then submits its server-generated requestId to execute a purchase. Checkout validates eligibility without reserving stock; transaction processing revalidates conditions and atomically consumes inventory. PostgreSQL is authoritative, while Redis supports write rate limiting. The README documents major API capabilities; some controller-to-service links are supported by the source index rather than full excerpts, and frontend-to-API transport details were not sampled.

Main entry points: [`frontend/src/api.ts`](https://github.com/vernardtan/flash-sale/blob/main/frontend/src/api.ts) (API client), [`backend/src/database/prisma.service.ts`](https://github.com/vernardtan/flash-sale/blob/main/backend/src/database/prisma.service.ts) (Prisma data access), [`backend/src/checkout/checkout.service.ts`](https://github.com/vernardtan/flash-sale/blob/main/backend/src/checkout/checkout.service.ts) (Checkout creation), [`backend/src/sale/sale.service.ts`](https://github.com/vernardtan/flash-sale/blob/main/backend/src/sale/sale.service.ts) (Sale rules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_storefront["Storefront"]
  node_app["Storefront UI<br/>[App.tsx]"]
  node_api["API client<br/>[api.ts]"]
end

subgraph group_discovery["Catalog and sale"]
  node_sale_api["Sale endpoint<br/>[sale.controller.ts]"]
  node_sale_logic["Sale rules<br/>[sale.service.ts]"]
  node_product_api["Product endpoint"]
  node_product_logic["Product catalog<br/>[product.service.ts]"]
end

subgraph group_commerce["Checkout and purchase"]
  node_checkout_api["Checkout endpoint"]
  node_checkout_logic["Checkout creation"]
  node_transaction_api["Transaction endpoint"]
  node_transaction_logic["Transaction processing"]
  node_purchase_api["Purchase lookup"]
  node_purchase_logic["Purchase query"]
  node_payment_methods["Payment options<br/>[payment-methods.ts]"]
end

subgraph group_platform["Shared infrastructure"]
  node_rate_limit["Rate limiter"]
  node_redis_client["Redis client<br/>[redis.service.ts]"]
  node_prisma["Prisma data access<br/>[prisma.service.ts]"]
  node_postgres[("PostgreSQL")]
  node_error_types["Domain errors<br/>[api.exception.ts]"]
end

node_shopper(("Shopper"))

node_shopper -->|"uses"| node_app
node_app -->|"calls"| node_api
node_api -.->|"requests"| node_sale_api
node_api -.->|"requests"| node_product_api
node_api -.->|"requests"| node_checkout_api
node_api -.->|"requests"| node_transaction_api
node_sale_api -->|"delegates"| node_sale_logic
node_product_api -->|"delegates"| node_product_logic
node_checkout_api -->|"delegates"| node_checkout_logic
node_transaction_api -->|"delegates"| node_transaction_logic
node_purchase_api -->|"delegates"| node_purchase_logic
node_checkout_api -->|"applies limit"| node_rate_limit
node_transaction_api -->|"applies limit"| node_rate_limit
node_rate_limit -->|"checks limits"| node_redis_client
node_product_logic -->|"derives status"| node_sale_logic
node_checkout_logic -->|"validates sale"| node_sale_logic
node_transaction_logic -->|"revalidates sale"| node_sale_logic
node_checkout_logic -->|"validates method"| node_payment_methods
node_checkout_logic -->|"creates checkout"| node_prisma
node_product_logic -->|"reads catalog"| node_prisma
node_sale_logic -->|"reads sale data"| node_prisma
node_transaction_logic -->|"claims and purchases"| node_prisma
node_purchase_logic -->|"reads purchases"| node_prisma
node_prisma -->|"queries"| node_postgres
node_checkout_logic -->|"throws errors"| node_error_types
node_transaction_logic -->|"throws errors"| node_error_types
node_purchase_api -.->|"returns purchase"| node_api
node_api -.->|"loads options"| node_payment_methods

click node_app "https://github.com/vernardtan/flash-sale/blob/main/frontend/src/App.tsx"
click node_api "https://github.com/vernardtan/flash-sale/blob/main/frontend/src/api.ts"
click node_sale_api "https://github.com/vernardtan/flash-sale/blob/main/backend/src/sale/sale.controller.ts"
click node_sale_logic "https://github.com/vernardtan/flash-sale/blob/main/backend/src/sale/sale.service.ts"
click node_product_api "https://github.com/vernardtan/flash-sale/blob/main/backend/src/product/product.controller.ts"
click node_product_logic "https://github.com/vernardtan/flash-sale/blob/main/backend/src/product/product.service.ts"
click node_checkout_api "https://github.com/vernardtan/flash-sale/blob/main/backend/src/checkout/checkout.controller.ts"
click node_checkout_logic "https://github.com/vernardtan/flash-sale/blob/main/backend/src/checkout/checkout.service.ts"
click node_transaction_api "https://github.com/vernardtan/flash-sale/blob/main/backend/src/purchase/transaction.controller.ts"
click node_transaction_logic "https://github.com/vernardtan/flash-sale/blob/main/backend/src/purchase/transaction.service.ts"
click node_purchase_api "https://github.com/vernardtan/flash-sale/blob/main/backend/src/purchase/purchase.controller.ts"
click node_purchase_logic "https://github.com/vernardtan/flash-sale/blob/main/backend/src/purchase/purchase.service.ts"
click node_payment_methods "https://github.com/vernardtan/flash-sale/blob/main/backend/src/payment/payment-methods.ts"
click node_rate_limit "https://github.com/vernardtan/flash-sale/blob/main/backend/src/common/rate-limit/rate-limit.guard.ts"
click node_redis_client "https://github.com/vernardtan/flash-sale/blob/main/backend/src/redis/redis.service.ts"
click node_prisma "https://github.com/vernardtan/flash-sale/blob/main/backend/src/database/prisma.service.ts"
click node_error_types "https://github.com/vernardtan/flash-sale/blob/main/backend/src/common/errors/api.exception.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_api toneBlue
class node_sale_api,node_sale_logic,node_product_api,node_product_logic toneAmber
class node_checkout_api,node_checkout_logic,node_transaction_api,node_transaction_logic,node_purchase_api,node_purchase_logic,node_payment_methods toneMint
class node_rate_limit,node_redis_client,node_prisma,node_postgres,node_error_types toneRose
class node_shopper toneIndigo
```

## Components

### Storefront

- [Storefront UI](https://github.com/vernardtan/flash-sale/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/vernardtan/flash-sale/blob/main/frontend/src/api.ts): `frontend/src/api.ts`

### Catalog and sale

- [Sale endpoint](https://github.com/vernardtan/flash-sale/blob/main/backend/src/sale/sale.controller.ts): `backend/src/sale/sale.controller.ts`
- [Sale rules](https://github.com/vernardtan/flash-sale/blob/main/backend/src/sale/sale.service.ts): `backend/src/sale/sale.service.ts`
- [Product endpoint](https://github.com/vernardtan/flash-sale/blob/main/backend/src/product/product.controller.ts): `backend/src/product/product.controller.ts`
- [Product catalog](https://github.com/vernardtan/flash-sale/blob/main/backend/src/product/product.service.ts): `backend/src/product/product.service.ts`

### Checkout and purchase

- [Checkout endpoint](https://github.com/vernardtan/flash-sale/blob/main/backend/src/checkout/checkout.controller.ts): `backend/src/checkout/checkout.controller.ts`
- [Checkout creation](https://github.com/vernardtan/flash-sale/blob/main/backend/src/checkout/checkout.service.ts): `backend/src/checkout/checkout.service.ts`
- [Transaction endpoint](https://github.com/vernardtan/flash-sale/blob/main/backend/src/purchase/transaction.controller.ts): `backend/src/purchase/transaction.controller.ts`
- [Transaction processing](https://github.com/vernardtan/flash-sale/blob/main/backend/src/purchase/transaction.service.ts): `backend/src/purchase/transaction.service.ts`
- [Purchase lookup](https://github.com/vernardtan/flash-sale/blob/main/backend/src/purchase/purchase.controller.ts): `backend/src/purchase/purchase.controller.ts`
- [Purchase query](https://github.com/vernardtan/flash-sale/blob/main/backend/src/purchase/purchase.service.ts): `backend/src/purchase/purchase.service.ts`
- [Payment options](https://github.com/vernardtan/flash-sale/blob/main/backend/src/payment/payment-methods.ts): `backend/src/payment/payment-methods.ts`

### Shared infrastructure

- [Rate limiter](https://github.com/vernardtan/flash-sale/blob/main/backend/src/common/rate-limit/rate-limit.guard.ts): `backend/src/common/rate-limit/rate-limit.guard.ts`
- [Redis client](https://github.com/vernardtan/flash-sale/blob/main/backend/src/redis/redis.service.ts): `backend/src/redis/redis.service.ts`
- [Prisma data access](https://github.com/vernardtan/flash-sale/blob/main/backend/src/database/prisma.service.ts): `backend/src/database/prisma.service.ts`
- **PostgreSQL**
- [Domain errors](https://github.com/vernardtan/flash-sale/blob/main/backend/src/common/errors/api.exception.ts): `backend/src/common/errors/api.exception.ts`

### Other components

- **Shopper**

## Connections

- Shopper → Storefront UI: uses (evidence: `README.md`)
- Storefront UI → API client: calls (evidence: `frontend/src/App.tsx`)
- API client → Sale endpoint: requests
- API client → Product endpoint: requests
- API client → Checkout endpoint: requests
- API client → Transaction endpoint: requests
- Sale endpoint → Sale rules: delegates (evidence: `backend/src/sale/sale.module.ts`)
- Product endpoint → Product catalog: delegates (evidence: `backend/src/product/product.controller.ts`)
- Checkout endpoint → Checkout creation: delegates (evidence: `backend/src/checkout/checkout.controller.ts`)
- Transaction endpoint → Transaction processing: delegates (evidence: `backend/src/purchase/transaction.controller.ts`)
- Purchase lookup → Purchase query: delegates (evidence: `backend/src/purchase/purchase.controller.ts`)
- Checkout endpoint → Rate limiter: applies limit (evidence: `backend/src/checkout/checkout.controller.ts`)
- Transaction endpoint → Rate limiter: applies limit (evidence: `backend/src/purchase/transaction.controller.ts`)
- Rate limiter → Redis client: checks limits (evidence: `backend/src/common/rate-limit/rate-limit.guard.ts`)
- Product catalog → Sale rules: derives status (evidence: `backend/src/product/product.service.ts`)
- Checkout creation → Sale rules: validates sale (evidence: `backend/src/checkout/checkout.service.ts`)
- Transaction processing → Sale rules: revalidates sale (evidence: `backend/src/purchase/transaction.service.ts`)
- Checkout creation → Payment options: validates method (evidence: `backend/src/checkout/checkout.service.ts`)
- Checkout creation → Prisma data access: creates checkout (evidence: `backend/src/checkout/checkout.service.ts`)
- Product catalog → Prisma data access: reads catalog (evidence: `backend/src/product/product.service.ts`)
- Sale rules → Prisma data access: reads sale data (evidence: `backend/src/sale/sale.service.ts`)
- Transaction processing → Prisma data access: claims and purchases (evidence: `backend/src/purchase/transaction.service.ts`)
- Purchase query → Prisma data access: reads purchases (evidence: `backend/src/purchase/purchase.service.ts`)
- Prisma data access → PostgreSQL: queries (evidence: `backend/src/database/prisma.service.ts`)
- Checkout creation → Domain errors: throws errors (evidence: `backend/src/checkout/checkout.service.ts`)
- Transaction processing → Domain errors: throws errors (evidence: `backend/src/purchase/transaction.service.ts`)
- Purchase lookup → API client: returns purchase
- API client → Payment options: loads options
