# vergo-wear/vergo-app architecture

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

- Interactive diagram: https://gitdiagram.com/vergo-wear/vergo-app
- Repository: https://github.com/vergo-wear/vergo-app

## Overview

Vergo Wear is a custom-apparel commerce and order-operations platform. Customers browse products, manage a cart, calculate shipping, and place COD or bank-transfer checkouts; reserved inventory and payment-proof review support order creation, followed by employee fulfillment and courier dispatch. Separate admin, identity, reviews, and notification capabilities are retained from the README and repository tree. Most unsampled feature links are documented capabilities rather than inspected calls, so they are shown as dashed with no evidence path.

Main entry points: [`backend/src/prisma/prisma.service.ts`](https://github.com/vergo-wear/vergo-app/blob/main/backend/src/prisma/prisma.service.ts) (PostgreSQL data), [`backend/src/orders/orders.service.ts`](https://github.com/vergo-wear/vergo-app/blob/main/backend/src/orders/orders.service.ts) (Checkout engine), [`frontend/src/app/(store)/checkout`](https://github.com/vergo-wear/vergo-app/tree/main/frontend/src/app/(store)/checkout) (Checkout), [`backend/src/admin/admin.service.ts`](https://github.com/vergo-wear/vergo-app/blob/main/backend/src/admin/admin.service.ts) (Admin services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_storefront["Customer commerce"]
  node_web["Storefront"]
  node_catalog_ui["Catalog browsing"]
  node_cart_ui["Cart<br/>[page.tsx]"]
  node_checkout_ui["Checkout"]
end

subgraph group_backend["Commerce services"]
  node_catalog["Product catalogue"]
  node_cart["Cart persistence<br/>[cart.service.ts]"]
  node_fees["Delivery fees"]
  node_orders_api["Order endpoints"]
  node_orders["Checkout engine<br/>[orders.service.ts]"]
  node_reservation["Stock reservation"]
  node_proof["Payment proofs"]
  node_reviews["Reviews moderation<br/>[reviews.service.ts]"]
  node_notifications["Notifications"]
end

subgraph group_operations["Store operations"]
  node_admin["Admin dashboard"]
  node_admin_api["Admin services<br/>[admin.service.ts]"]
  node_employees_ui["Employee workspace"]
  node_employees["Fulfillment queue"]
  node_citypak["Citypak logistics"]
end

subgraph group_platform["Identity and infrastructure"]
  node_cloudinary["Media storage"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_auth_guard["Request auth"]
  node_roles["Role access<br/>[roles.guard.ts]"]
  node_database[("PostgreSQL data<br/>[prisma.service.ts]")]
end

node_customer(("Customer"))
node_courier{{"Citypak courier"}}

node_customer -.->|"browses"| node_web
node_web -.->|"opens"| node_catalog_ui
node_catalog_ui -.->|"requests products"| node_catalog
node_customer -.->|"manages cart"| node_cart_ui
node_cart_ui -.->|"persists cart"| node_cart
node_customer -.->|"checks out"| node_checkout_ui
node_checkout_ui -.->|"calculates delivery"| node_fees
node_checkout_ui -.->|"submits order"| node_orders_api
node_orders_api -->|"creates checkout"| node_orders
node_orders -.->|"reserves stock"| node_reservation
node_orders -.->|"audits payment"| node_proof
node_proof -.->|"uploads receipt"| node_cloudinary
node_admin -.->|"manages operations"| node_admin_api
node_admin_api -->|"stores product media"| node_cloudinary
node_employees_ui -.->|"fulfills orders"| node_employees
node_employees -->|"reads and writes"| node_database
node_admin_api -.->|"reads and writes"| node_database
node_orders -.->|"reads and writes"| node_database
node_auth -->|"reads and writes"| node_database
node_auth_guard -->|"loads profile"| node_database
node_auth_guard -->|"provides identity"| node_roles
node_citypak -.->|"registers shipments"| node_courier
node_reviews -->|"reads and writes"| node_database
node_notifications -.->|"sends updates"| node_customer

click node_web "https://github.com/vergo-wear/vergo-app/tree/main/frontend/src/app/(store)"
click node_catalog_ui "https://github.com/vergo-wear/vergo-app/tree/main/frontend/src/app/(store)/collection"
click node_cart_ui "https://github.com/vergo-wear/vergo-app/blob/main/frontend/src/app/(store)/cart/page.tsx"
click node_checkout_ui "https://github.com/vergo-wear/vergo-app/tree/main/frontend/src/app/(store)/checkout"
click node_catalog "https://github.com/vergo-wear/vergo-app/blob/main/backend/src/product-catalogue/product-catalogue.service.ts"
click node_cart "https://github.com/vergo-wear/vergo-app/blob/main/backend/src/cart/cart.service.ts"
click node_fees "https://github.com/vergo-wear/vergo-app/blob/main/backend/src/delivery-fees/delivery-fees.service.ts"
click node_orders_api "https://github.com/vergo-wear/vergo-app/blob/main/backend/src/orders/orders.controller.ts"
click node_orders "https://github.com/vergo-wear/vergo-app/blob/main/backend/src/orders/orders.service.ts"
click node_reservation "https://github.com/vergo-wear/vergo-app/blob/main/backend/src/stock-reservation/stock-reservation.service.ts"
click node_proof "https://github.com/vergo-wear/vergo-app/blob/main/backend/src/payment-proof/payment-proof.service.ts"
click node_cloudinary "https://github.com/vergo-wear/vergo-app/blob/main/backend/src/cloudinary/cloudinary.service.ts"
click node_auth "https://github.com/vergo-wear/vergo-app/blob/main/backend/src/auth/auth.service.ts"
click node_auth_guard "https://github.com/vergo-wear/vergo-app/blob/main/backend/src/auth/guards/supabase-auth.guard.ts"
click node_roles "https://github.com/vergo-wear/vergo-app/blob/main/backend/src/auth/guards/roles.guard.ts"
click node_database "https://github.com/vergo-wear/vergo-app/blob/main/backend/src/prisma/prisma.service.ts"
click node_admin "https://github.com/vergo-wear/vergo-app/tree/main/frontend/src/app/(admin)/admin"
click node_admin_api "https://github.com/vergo-wear/vergo-app/blob/main/backend/src/admin/admin.service.ts"
click node_employees_ui "https://github.com/vergo-wear/vergo-app/tree/main/frontend/src/app/(employee)/employee"
click node_employees "https://github.com/vergo-wear/vergo-app/blob/main/backend/src/employees/employees.service.ts"
click node_citypak "https://github.com/vergo-wear/vergo-app/tree/main/backend/src/integrations/citypak"
click node_reviews "https://github.com/vergo-wear/vergo-app/blob/main/backend/src/reviews/reviews.service.ts"
click node_notifications "https://github.com/vergo-wear/vergo-app/blob/main/backend/src/notifications/notifications.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_web,node_catalog_ui,node_cart_ui,node_checkout_ui toneBlue
class node_catalog,node_cart,node_fees,node_orders_api,node_orders,node_reservation,node_proof,node_reviews,node_notifications toneAmber
class node_admin,node_admin_api,node_employees_ui,node_employees,node_citypak toneMint
class node_cloudinary,node_auth,node_auth_guard,node_roles,node_database toneRose
class node_customer,node_courier toneIndigo
```

## Components

### Customer commerce

- [Storefront](https://github.com/vergo-wear/vergo-app/tree/main/frontend/src/app/(store)): `frontend/src/app/(store)`
- [Catalog browsing](https://github.com/vergo-wear/vergo-app/tree/main/frontend/src/app/(store)/collection): `frontend/src/app/(store)/collection`
- [Cart](https://github.com/vergo-wear/vergo-app/blob/main/frontend/src/app/(store)/cart/page.tsx): `frontend/src/app/(store)/cart/page.tsx`
- [Checkout](https://github.com/vergo-wear/vergo-app/tree/main/frontend/src/app/(store)/checkout): `frontend/src/app/(store)/checkout`

### Commerce services

- [Product catalogue](https://github.com/vergo-wear/vergo-app/blob/main/backend/src/product-catalogue/product-catalogue.service.ts): `backend/src/product-catalogue/product-catalogue.service.ts`
- [Cart persistence](https://github.com/vergo-wear/vergo-app/blob/main/backend/src/cart/cart.service.ts): `backend/src/cart/cart.service.ts`
- [Delivery fees](https://github.com/vergo-wear/vergo-app/blob/main/backend/src/delivery-fees/delivery-fees.service.ts): `backend/src/delivery-fees/delivery-fees.service.ts`
- [Order endpoints](https://github.com/vergo-wear/vergo-app/blob/main/backend/src/orders/orders.controller.ts): `backend/src/orders/orders.controller.ts`
- [Checkout engine](https://github.com/vergo-wear/vergo-app/blob/main/backend/src/orders/orders.service.ts): `backend/src/orders/orders.service.ts`
- [Stock reservation](https://github.com/vergo-wear/vergo-app/blob/main/backend/src/stock-reservation/stock-reservation.service.ts): `backend/src/stock-reservation/stock-reservation.service.ts`
- [Payment proofs](https://github.com/vergo-wear/vergo-app/blob/main/backend/src/payment-proof/payment-proof.service.ts): `backend/src/payment-proof/payment-proof.service.ts`
- [Reviews moderation](https://github.com/vergo-wear/vergo-app/blob/main/backend/src/reviews/reviews.service.ts): `backend/src/reviews/reviews.service.ts`
- [Notifications](https://github.com/vergo-wear/vergo-app/blob/main/backend/src/notifications/notifications.service.ts): `backend/src/notifications/notifications.service.ts`

### Store operations

- [Admin dashboard](https://github.com/vergo-wear/vergo-app/tree/main/frontend/src/app/(admin)/admin): `frontend/src/app/(admin)/admin`
- [Admin services](https://github.com/vergo-wear/vergo-app/blob/main/backend/src/admin/admin.service.ts): `backend/src/admin/admin.service.ts`
- [Employee workspace](https://github.com/vergo-wear/vergo-app/tree/main/frontend/src/app/(employee)/employee): `frontend/src/app/(employee)/employee`
- [Fulfillment queue](https://github.com/vergo-wear/vergo-app/blob/main/backend/src/employees/employees.service.ts): `backend/src/employees/employees.service.ts`
- [Citypak logistics](https://github.com/vergo-wear/vergo-app/tree/main/backend/src/integrations/citypak): `backend/src/integrations/citypak`

### Identity and infrastructure

- [Media storage](https://github.com/vergo-wear/vergo-app/blob/main/backend/src/cloudinary/cloudinary.service.ts): `backend/src/cloudinary/cloudinary.service.ts`
- [Authentication](https://github.com/vergo-wear/vergo-app/blob/main/backend/src/auth/auth.service.ts): `backend/src/auth/auth.service.ts`
- [Request auth](https://github.com/vergo-wear/vergo-app/blob/main/backend/src/auth/guards/supabase-auth.guard.ts): `backend/src/auth/guards/supabase-auth.guard.ts`
- [Role access](https://github.com/vergo-wear/vergo-app/blob/main/backend/src/auth/guards/roles.guard.ts): `backend/src/auth/guards/roles.guard.ts`
- [PostgreSQL data](https://github.com/vergo-wear/vergo-app/blob/main/backend/src/prisma/prisma.service.ts): `backend/src/prisma/prisma.service.ts`

### Other components

- **Customer**
- **Citypak courier**

## Connections

- Customer → Storefront: browses
- Storefront → Catalog browsing: opens
- Catalog browsing → Product catalogue: requests products
- Customer → Cart: manages cart
- Cart → Cart persistence: persists cart
- Customer → Checkout: checks out
- Checkout → Delivery fees: calculates delivery
- Checkout → Order endpoints: submits order
- Order endpoints → Checkout engine: creates checkout (evidence: `backend/src/orders/orders.controller.ts`)
- Checkout engine → Stock reservation: reserves stock
- Checkout engine → Payment proofs: audits payment
- Payment proofs → Media storage: uploads receipt
- Admin dashboard → Admin services: manages operations
- Admin services → Media storage: stores product media (evidence: `backend/src/admin/admin.controller.ts`)
- Employee workspace → Fulfillment queue: fulfills orders
- Fulfillment queue → PostgreSQL data: reads and writes (evidence: `backend/src/employees/employees.service.ts`)
- Admin services → PostgreSQL data: reads and writes (evidence: `backend/src/admin/admin.service.ts`)
- Checkout engine → PostgreSQL data: reads and writes
- Authentication → PostgreSQL data: reads and writes (evidence: `backend/src/auth/auth.service.ts`)
- Request auth → PostgreSQL data: loads profile (evidence: `backend/src/auth/guards/supabase-auth.guard.ts`)
- Request auth → Role access: provides identity (evidence: `backend/src/auth/guards/roles.guard.ts`)
- Citypak logistics → Citypak courier: registers shipments
- Reviews moderation → PostgreSQL data: reads and writes (evidence: `backend/src/reviews/reviews.service.ts`)
- Notifications → Customer: sends updates