# ncd426/brewlite-2 architecture

> Architecture diagram of the GitHub repository ncd426/brewlite-2, 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/ncd426/brewlite-2
- Repository: https://github.com/ncd426/brewlite-2

## Overview

BrewLite is a drink-ordering application with a Next.js storefront, NestJS API, and PostgreSQL persistence. Customers browse products, build a cart, preview promotions, place an order, and pay online; authenticated users can view profiles and order history. The API separately supports VNPay IPN verification and simulated counter sales, plus administrative product, inventory, and user management. The graph includes these documented capabilities; some frontend-to-API links are shown as unverified because the API client implementation was not excerpted.

Main entry points: [`apps/api/src/payments/payments.service.ts`](https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/payments/payments.service.ts) (Payment processing), [`apps/api/src/prisma/prisma.service.ts`](https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/prisma/prisma.service.ts) (PostgreSQL), [`apps/api/src/orders/orders.service.ts`](https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/orders/orders.service.ts) (Order processing), [`apps/api/src/orders/promotion-preview.service.ts`](https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/orders/promotion-preview.service.ts) (Promotion preview)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_storefront["Customer storefront"]
  node_storefront["Storefront pages<br/>[page.tsx]"]
  node_productdetail["Product details<br/>[page.tsx]"]
  node_cart["Cart<br/>[page.tsx]"]
  node_cartstate["Cart state<br/>[useCartStore.ts]"]
  node_checkout["Checkout<br/>[page.tsx]"]
  node_qrpage["QR checkout<br/>[page.tsx]"]
  node_history["Order history<br/>[page.tsx]"]
end

subgraph group_commerce["Ordering and catalog"]
  node_productsapi["Product API"]
  node_products["Product catalog"]
  node_ordersapi["Order API"]
  node_orders["Order processing<br/>[orders.service.ts]"]
  node_promotionpreview["Promotion preview"]
  node_pricing["Pricing rules<br/>[pricing.ts]"]
  node_promotionrules["Promotion rules<br/>[promotion-rule.ts]"]
  node_inventoryrecipe["Recipe inventory"]
end

subgraph group_payments["Payments and rewards"]
  node_paymentsapi["Payment API"]
  node_payments["Payment processing"]
  node_gateway["Payment gateways"]
  node_webhook["VNPay IPN"]
  node_loyalty["Loyalty points<br/>[loyalty-points.ts]"]
end

subgraph group_operations["Staff and administration"]
  node_counter["Counter sales"]
  node_admin["Admin console"]
  node_backoffice["Backoffice services"]
end

subgraph group_platform["Identity and persistence"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_users["User accounts<br/>[users.service.ts]"]
  node_database[("PostgreSQL<br/>[prisma.service.ts]")]
end

node_customer(("Customer"))
node_vnpay{{"VNPay Sandbox"}}
node_staff(("Staff"))

node_customer -->|"browses"| node_storefront
node_storefront -.->|"loads catalog"| node_productsapi
node_customer -->|"selects drink"| node_productdetail
node_productdetail -.->|"adds item"| node_cartstate
node_cart -->|"reads cart"| node_cartstate
node_cart -->|"continues to"| node_checkout
node_checkout -.->|"requests quote"| node_promotionpreview
node_checkout -.->|"submits order"| node_ordersapi
node_ordersapi -->|"delegates to"| node_orders
node_orders -->|"calculates price"| node_pricing
node_orders -->|"resolves promotion"| node_promotionrules
node_orders -->|"checks ingredients"| node_inventoryrecipe
node_promotionpreview -->|"uses pricing"| node_pricing
node_promotionpreview -->|"resolves promotion"| node_promotionrules
node_promotionpreview -->|"checks availability"| node_inventoryrecipe
node_orders -->|"reads and writes"| node_database
node_productsapi -->|"delegates to"| node_products
node_products -->|"reads products"| node_database
node_products -->|"checks stock"| node_inventoryrecipe
node_customer -->|"starts payment"| node_paymentsapi
node_paymentsapi -->|"processes payment"| node_payments
node_payments -->|"creates session"| node_gateway
node_payments -->|"redeems points"| node_loyalty
node_payments -->|"records payment"| node_database
node_payments -->|"requests checkout"| node_vnpay
node_vnpay -->|"sends IPN"| node_webhook
node_webhook -->|"verifies signature"| node_gateway
node_webhook -->|"processes result"| node_payments
node_customer -->|"views purchases"| node_history
node_history -.->|"loads orders"| node_ordersapi
node_staff -->|"records sale"| node_counter
node_counter -->|"writes sale"| node_database
node_admin -->|"manages operations"| node_backoffice
node_backoffice -->|"reads and writes"| node_database
node_customer -->|"registers or signs in"| node_auth
node_auth -->|"looks up or creates"| node_users
node_users -->|"persists accounts"| node_database

click node_storefront "https://github.com/ncd426/brewlite-2/blob/main/apps/web/app/page.tsx"
click node_productdetail "https://github.com/ncd426/brewlite-2/blob/main/apps/web/app/products/%5Bid%5D/page.tsx"
click node_cart "https://github.com/ncd426/brewlite-2/blob/main/apps/web/app/cart/page.tsx"
click node_cartstate "https://github.com/ncd426/brewlite-2/blob/main/apps/web/lib/useCartStore.ts"
click node_checkout "https://github.com/ncd426/brewlite-2/blob/main/apps/web/app/checkout/page.tsx"
click node_qrpage "https://github.com/ncd426/brewlite-2/blob/main/apps/web/app/checkout/qr/page.tsx"
click node_history "https://github.com/ncd426/brewlite-2/blob/main/apps/web/app/orders/page.tsx"
click node_productsapi "https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/products/products.controller.ts"
click node_products "https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/products/products.service.ts"
click node_ordersapi "https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/orders/orders.controller.ts"
click node_orders "https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/orders/orders.service.ts"
click node_promotionpreview "https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/orders/promotion-preview.service.ts"
click node_pricing "https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/orders/pricing.ts"
click node_promotionrules "https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/orders/promotion-rule.ts"
click node_inventoryrecipe "https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/inventory/recipe-inventory.ts"
click node_paymentsapi "https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/payments/payments.controller.ts"
click node_payments "https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/payments/payments.service.ts"
click node_gateway "https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/payments/payment-gateways.ts"
click node_webhook "https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/payments/payments-webhook.controller.ts"
click node_loyalty "https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/payments/loyalty-points.ts"
click node_counter "https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/backoffice/counter-sales.service.ts"
click node_admin "https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/backoffice/admin.controller.ts"
click node_backoffice "https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/backoffice/backoffice.service.ts"
click node_auth "https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/auth/auth.service.ts"
click node_users "https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/users/users.service.ts"
click node_database "https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/prisma/prisma.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_storefront,node_productdetail,node_cart,node_cartstate,node_checkout,node_qrpage,node_history toneBlue
class node_productsapi,node_products,node_ordersapi,node_orders,node_promotionpreview,node_pricing,node_promotionrules,node_inventoryrecipe toneAmber
class node_paymentsapi,node_payments,node_gateway,node_webhook,node_loyalty toneMint
class node_counter,node_admin,node_backoffice toneRose
class node_auth,node_users,node_database,node_customer,node_vnpay,node_staff toneIndigo
```

## Components

### Customer storefront

- [Storefront pages](https://github.com/ncd426/brewlite-2/blob/main/apps/web/app/page.tsx): `apps/web/app/page.tsx`
- [Product details](https://github.com/ncd426/brewlite-2/blob/main/apps/web/app/products/%5Bid%5D/page.tsx): `apps/web/app/products/[id]/page.tsx`
- [Cart](https://github.com/ncd426/brewlite-2/blob/main/apps/web/app/cart/page.tsx): `apps/web/app/cart/page.tsx`
- [Cart state](https://github.com/ncd426/brewlite-2/blob/main/apps/web/lib/useCartStore.ts): `apps/web/lib/useCartStore.ts`
- [Checkout](https://github.com/ncd426/brewlite-2/blob/main/apps/web/app/checkout/page.tsx): `apps/web/app/checkout/page.tsx`
- [QR checkout](https://github.com/ncd426/brewlite-2/blob/main/apps/web/app/checkout/qr/page.tsx): `apps/web/app/checkout/qr/page.tsx`
- [Order history](https://github.com/ncd426/brewlite-2/blob/main/apps/web/app/orders/page.tsx): `apps/web/app/orders/page.tsx`

### Ordering and catalog

- [Product API](https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/products/products.controller.ts): `apps/api/src/products/products.controller.ts`
- [Product catalog](https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/products/products.service.ts): `apps/api/src/products/products.service.ts`
- [Order API](https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/orders/orders.controller.ts): `apps/api/src/orders/orders.controller.ts`
- [Order processing](https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/orders/orders.service.ts): `apps/api/src/orders/orders.service.ts`
- [Promotion preview](https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/orders/promotion-preview.service.ts): `apps/api/src/orders/promotion-preview.service.ts`
- [Pricing rules](https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/orders/pricing.ts): `apps/api/src/orders/pricing.ts`
- [Promotion rules](https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/orders/promotion-rule.ts): `apps/api/src/orders/promotion-rule.ts`
- [Recipe inventory](https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/inventory/recipe-inventory.ts): `apps/api/src/inventory/recipe-inventory.ts`

### Payments and rewards

- [Payment API](https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/payments/payments.controller.ts): `apps/api/src/payments/payments.controller.ts`
- [Payment processing](https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/payments/payments.service.ts): `apps/api/src/payments/payments.service.ts`
- [Payment gateways](https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/payments/payment-gateways.ts): `apps/api/src/payments/payment-gateways.ts`
- [VNPay IPN](https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/payments/payments-webhook.controller.ts): `apps/api/src/payments/payments-webhook.controller.ts`
- [Loyalty points](https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/payments/loyalty-points.ts): `apps/api/src/payments/loyalty-points.ts`

### Staff and administration

- [Counter sales](https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/backoffice/counter-sales.service.ts): `apps/api/src/backoffice/counter-sales.service.ts`
- [Admin console](https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/backoffice/admin.controller.ts): `apps/api/src/backoffice/admin.controller.ts`
- [Backoffice services](https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/backoffice/backoffice.service.ts): `apps/api/src/backoffice/backoffice.service.ts`

### Identity and persistence

- [Authentication](https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/auth/auth.service.ts): `apps/api/src/auth/auth.service.ts`
- [User accounts](https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/users/users.service.ts): `apps/api/src/users/users.service.ts`
- [PostgreSQL](https://github.com/ncd426/brewlite-2/blob/main/apps/api/src/prisma/prisma.service.ts): `apps/api/src/prisma/prisma.service.ts`

### Other components

- **Customer**
- **VNPay Sandbox**
- **Staff**

## Connections

- Customer → Storefront pages: browses
- Storefront pages → Product API: loads catalog
- Customer → Product details: selects drink
- Product details → Cart state: adds item
- Cart → Cart state: reads cart (evidence: `apps/web/app/cart/page.tsx`)
- Cart → Checkout: continues to
- Checkout → Promotion preview: requests quote
- Checkout → Order API: submits order
- Order API → Order processing: delegates to (evidence: `apps/api/src/orders/orders.controller.ts`)
- Order processing → Pricing rules: calculates price (evidence: `apps/api/src/orders/orders.service.ts`)
- Order processing → Promotion rules: resolves promotion (evidence: `apps/api/src/orders/orders.service.ts`)
- Order processing → Recipe inventory: checks ingredients (evidence: `apps/api/src/orders/orders.service.ts`)
- Promotion preview → Pricing rules: uses pricing (evidence: `apps/api/src/orders/promotion-preview.service.ts`)
- Promotion preview → Promotion rules: resolves promotion (evidence: `apps/api/src/orders/promotion-preview.service.ts`)
- Promotion preview → Recipe inventory: checks availability (evidence: `apps/api/src/orders/promotion-preview.service.ts`)
- Order processing → PostgreSQL: reads and writes (evidence: `apps/api/src/orders/orders.service.ts`)
- Product API → Product catalog: delegates to (evidence: `apps/api/src/products/products.controller.ts`)
- Product catalog → PostgreSQL: reads products (evidence: `apps/api/src/products/products.service.ts`)
- Product catalog → Recipe inventory: checks stock (evidence: `apps/api/src/products/products.service.ts`)
- Customer → Payment API: starts payment
- Payment API → Payment processing: processes payment (evidence: `apps/api/src/payments/payments.controller.ts`)
- Payment processing → Payment gateways: creates session (evidence: `apps/api/src/payments/payments.service.ts`)
- Payment processing → Loyalty points: redeems points (evidence: `apps/api/src/payments/payments.service.ts`)
- Payment processing → PostgreSQL: records payment (evidence: `apps/api/src/payments/payments.service.ts`)
- Payment processing → VNPay Sandbox: requests checkout
- VNPay Sandbox → VNPay IPN: sends IPN
- VNPay IPN → Payment gateways: verifies signature (evidence: `apps/api/src/payments/payments-webhook.controller.ts`)
- VNPay IPN → Payment processing: processes result (evidence: `apps/api/src/payments/payments-webhook.controller.ts`)
- Customer → Order history: views purchases
- Order history → Order API: loads orders
- Staff → Counter sales: records sale
- Counter sales → PostgreSQL: writes sale (evidence: `apps/api/src/backoffice/counter-sales.service.ts`)
- Admin console → Backoffice services: manages operations (evidence: `apps/api/src/backoffice/admin.controller.ts`)
- Backoffice services → PostgreSQL: reads and writes (evidence: `apps/api/src/backoffice/backoffice.service.ts`)
- Customer → Authentication: registers or signs in
- Authentication → User accounts: looks up or creates (evidence: `apps/api/src/auth/auth.service.ts`)
- User accounts → PostgreSQL: persists accounts (evidence: `apps/api/src/users/users.service.ts`)
