# shanedesal/pfs-platform architecture

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

- Interactive diagram: https://gitdiagram.com/shanedesal/pfs-platform
- Repository: https://github.com/shanedesal/pfs-platform

## Overview

PFS is a full-stack marketplace: customers browse products, authenticate, maintain a cart and address book, and place and track orders; administrators manage catalog, orders, and customer accounts. The Next.js storefront calls an Express API whose controllers use Prisma/PostgreSQL. Authentication, email verification, image storage, and admin operations are distinct supporting capabilities. The README documents the main user flows; several controller and route files were not sampled, so uncertain wiring is omitted or shown as unverified.

Main entry points: [`server/src/index.ts`](https://github.com/shanedesal/pfs-platform/blob/master/server/src/index.ts) (Express API), [`server/src/config/db.ts`](https://github.com/shanedesal/pfs-platform/blob/master/server/src/config/db.ts) (Prisma Client), [`server/src/controllers/auth.controller.ts`](https://github.com/shanedesal/pfs-platform/blob/master/server/src/controllers/auth.controller.ts) (Auth Controller), [`web/src/lib/api.ts`](https://github.com/shanedesal/pfs-platform/blob/master/web/src/lib/api.ts) (API Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_storefront["Storefront"]
  node_store_pages["Store Pages"]
  node_store_components["Storefront UI"]
  node_web_api["API Client<br/>[api.ts]"]
end

subgraph group_identity["Identity"]
  node_auth_ui["Auth Pages<br/>[page.tsx]"]
  node_auth_state["Auth State<br/>[auth-context.tsx]"]
  node_auth_routes["Auth Routes<br/>[auth.ts]"]
  node_auth_controller["Auth Controller<br/>[auth.controller.ts]"]
  node_auth_middleware["Auth Guard<br/>[auth.middleware.ts]"]
  node_jwt_tokens["JWT and Tokens<br/>[jwt.ts]"]
  node_verification_email["Verification Email"]
end

subgraph group_commerce["Commerce"]
  node_cart_controller["Cart Controller<br/>[cart.controller.ts]"]
  node_order_controller["Order Controller"]
  node_address_controller["Address Controller"]
  node_order_format["Order Formatting"]
end

subgraph group_backoffice["Admin Back Office"]
  node_admin_pages["Admin Pages"]
  node_admin_clients["Admin API Clients"]
  node_admin_product_controller["Product Admin"]
  node_admin_category_controller["Category Admin"]
  node_admin_order_controller["Order Admin"]
  node_admin_customer_controller["Customer Admin"]
end

subgraph group_platform["API and Integrations"]
  node_api_bootstrap["Express API<br/>[index.ts]"]
  node_database_client["Prisma Client<br/>[db.ts]"]
  node_postgres[("PostgreSQL")]
  node_image_storage[("Supabase Storage")]
  node_email_provider["Brevo Email"]
end

node_customer(("Customer"))
node_admin_user(("Administrator"))

node_customer -->|"browses"| node_store_pages
node_store_pages -.->|"renders"| node_store_components
node_store_pages -.->|"requests data"| node_web_api
node_customer -->|"signs in"| node_auth_ui
node_auth_ui -->|"submits credentials"| node_web_api
node_auth_ui -->|"applies user"| node_auth_state
node_web_api -->|"calls API"| node_api_bootstrap
node_api_bootstrap -->|"mounts routes"| node_auth_routes
node_auth_routes -->|"dispatches"| node_auth_controller
node_auth_routes -->|"guards requests"| node_auth_middleware
node_auth_controller -->|"reads and writes"| node_database_client
node_auth_controller -->|"issues tokens"| node_jwt_tokens
node_auth_middleware -->|"verifies tokens"| node_jwt_tokens
node_auth_controller -->|"sends verification"| node_verification_email
node_verification_email -.->|"delivers email"| node_email_provider
node_customer -->|"manages cart"| node_store_components
node_store_components -.->|"requests commerce"| node_web_api
node_api_bootstrap -.->|"routes cart"| node_cart_controller
node_api_bootstrap -.->|"routes orders"| node_order_controller
node_api_bootstrap -.->|"routes addresses"| node_address_controller
node_order_controller -->|"creates and reads orders"| node_database_client
node_order_controller -->|"formats orders"| node_order_format
node_address_controller -->|"manages addresses"| node_database_client
node_database_client -->|"persists records"| node_postgres
node_admin_user -->|"manages marketplace"| node_admin_pages
node_admin_pages -.->|"requests admin data"| node_admin_clients
node_admin_clients -.->|"calls API"| node_api_bootstrap
node_api_bootstrap -.->|"routes product admin"| node_admin_product_controller
node_api_bootstrap -.->|"routes category admin"| node_admin_category_controller
node_api_bootstrap -.->|"routes order admin"| node_admin_order_controller
node_api_bootstrap -.->|"routes customer admin"| node_admin_customer_controller
node_admin_product_controller -->|"manages products"| node_database_client
node_admin_product_controller -->|"uploads images"| node_image_storage
node_admin_customer_controller -->|"manages customers"| node_database_client

click node_store_pages "https://github.com/shanedesal/pfs-platform/tree/master/web/src/app"
click node_store_components "https://github.com/shanedesal/pfs-platform/tree/master/web/src/components/storefront"
click node_web_api "https://github.com/shanedesal/pfs-platform/blob/master/web/src/lib/api.ts"
click node_auth_ui "https://github.com/shanedesal/pfs-platform/blob/master/web/src/app/login/page.tsx"
click node_auth_state "https://github.com/shanedesal/pfs-platform/blob/master/web/src/lib/auth-context.tsx"
click node_auth_routes "https://github.com/shanedesal/pfs-platform/blob/master/server/src/routes/auth.ts"
click node_auth_controller "https://github.com/shanedesal/pfs-platform/blob/master/server/src/controllers/auth.controller.ts"
click node_auth_middleware "https://github.com/shanedesal/pfs-platform/blob/master/server/src/middleware/auth.middleware.ts"
click node_jwt_tokens "https://github.com/shanedesal/pfs-platform/blob/master/server/src/utils/jwt.ts"
click node_verification_email "https://github.com/shanedesal/pfs-platform/blob/master/server/src/services/email/verification-emails.ts"
click node_cart_controller "https://github.com/shanedesal/pfs-platform/blob/master/server/src/controllers/cart.controller.ts"
click node_order_controller "https://github.com/shanedesal/pfs-platform/blob/master/server/src/controllers/orders.controller.ts"
click node_address_controller "https://github.com/shanedesal/pfs-platform/blob/master/server/src/controllers/addresses.controller.ts"
click node_order_format "https://github.com/shanedesal/pfs-platform/blob/master/server/src/utils/order-formatting.ts"
click node_admin_pages "https://github.com/shanedesal/pfs-platform/tree/master/web/src/app/admin"
click node_admin_clients "https://github.com/shanedesal/pfs-platform/tree/master/web/src/lib/admin"
click node_admin_product_controller "https://github.com/shanedesal/pfs-platform/blob/master/server/src/controllers/admin-products.controller.ts"
click node_admin_category_controller "https://github.com/shanedesal/pfs-platform/blob/master/server/src/controllers/admin-categories.controller.ts"
click node_admin_order_controller "https://github.com/shanedesal/pfs-platform/blob/master/server/src/controllers/admin-orders.controller.ts"
click node_admin_customer_controller "https://github.com/shanedesal/pfs-platform/blob/master/server/src/controllers/admin-customers.controller.ts"
click node_api_bootstrap "https://github.com/shanedesal/pfs-platform/blob/master/server/src/index.ts"
click node_database_client "https://github.com/shanedesal/pfs-platform/blob/master/server/src/config/db.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_store_pages,node_store_components,node_web_api toneBlue
class node_auth_ui,node_auth_state,node_auth_routes,node_auth_controller,node_auth_middleware,node_jwt_tokens,node_verification_email toneAmber
class node_cart_controller,node_order_controller,node_address_controller,node_order_format toneMint
class node_admin_pages,node_admin_clients,node_admin_product_controller,node_admin_category_controller,node_admin_order_controller,node_admin_customer_controller toneRose
class node_api_bootstrap,node_database_client,node_postgres,node_image_storage,node_email_provider,node_customer,node_admin_user toneIndigo
```

## Components

### Storefront

- [Store Pages](https://github.com/shanedesal/pfs-platform/tree/master/web/src/app): `web/src/app`
- [Storefront UI](https://github.com/shanedesal/pfs-platform/tree/master/web/src/components/storefront): `web/src/components/storefront`
- [API Client](https://github.com/shanedesal/pfs-platform/blob/master/web/src/lib/api.ts): `web/src/lib/api.ts`

### Identity

- [Auth Pages](https://github.com/shanedesal/pfs-platform/blob/master/web/src/app/login/page.tsx): `web/src/app/login/page.tsx`
- [Auth State](https://github.com/shanedesal/pfs-platform/blob/master/web/src/lib/auth-context.tsx): `web/src/lib/auth-context.tsx`
- [Auth Routes](https://github.com/shanedesal/pfs-platform/blob/master/server/src/routes/auth.ts): `server/src/routes/auth.ts`
- [Auth Controller](https://github.com/shanedesal/pfs-platform/blob/master/server/src/controllers/auth.controller.ts): `server/src/controllers/auth.controller.ts`
- [Auth Guard](https://github.com/shanedesal/pfs-platform/blob/master/server/src/middleware/auth.middleware.ts): `server/src/middleware/auth.middleware.ts`
- [JWT and Tokens](https://github.com/shanedesal/pfs-platform/blob/master/server/src/utils/jwt.ts): `server/src/utils/jwt.ts`
- [Verification Email](https://github.com/shanedesal/pfs-platform/blob/master/server/src/services/email/verification-emails.ts): `server/src/services/email/verification-emails.ts`

### Commerce

- [Cart Controller](https://github.com/shanedesal/pfs-platform/blob/master/server/src/controllers/cart.controller.ts): `server/src/controllers/cart.controller.ts`
- [Order Controller](https://github.com/shanedesal/pfs-platform/blob/master/server/src/controllers/orders.controller.ts): `server/src/controllers/orders.controller.ts`
- [Address Controller](https://github.com/shanedesal/pfs-platform/blob/master/server/src/controllers/addresses.controller.ts): `server/src/controllers/addresses.controller.ts`
- [Order Formatting](https://github.com/shanedesal/pfs-platform/blob/master/server/src/utils/order-formatting.ts): `server/src/utils/order-formatting.ts`

### Admin Back Office

- [Admin Pages](https://github.com/shanedesal/pfs-platform/tree/master/web/src/app/admin): `web/src/app/admin`
- [Admin API Clients](https://github.com/shanedesal/pfs-platform/tree/master/web/src/lib/admin): `web/src/lib/admin`
- [Product Admin](https://github.com/shanedesal/pfs-platform/blob/master/server/src/controllers/admin-products.controller.ts): `server/src/controllers/admin-products.controller.ts`
- [Category Admin](https://github.com/shanedesal/pfs-platform/blob/master/server/src/controllers/admin-categories.controller.ts): `server/src/controllers/admin-categories.controller.ts`
- [Order Admin](https://github.com/shanedesal/pfs-platform/blob/master/server/src/controllers/admin-orders.controller.ts): `server/src/controllers/admin-orders.controller.ts`
- [Customer Admin](https://github.com/shanedesal/pfs-platform/blob/master/server/src/controllers/admin-customers.controller.ts): `server/src/controllers/admin-customers.controller.ts`

### API and Integrations

- [Express API](https://github.com/shanedesal/pfs-platform/blob/master/server/src/index.ts): `server/src/index.ts`
- [Prisma Client](https://github.com/shanedesal/pfs-platform/blob/master/server/src/config/db.ts): `server/src/config/db.ts`
- **PostgreSQL**
- **Supabase Storage**
- **Brevo Email**

### Other components

- **Customer**
- **Administrator**

## Connections

- Customer → Store Pages: browses
- Store Pages → Storefront UI: renders
- Store Pages → API Client: requests data
- Customer → Auth Pages: signs in
- Auth Pages → API Client: submits credentials
- Auth Pages → Auth State: applies user
- API Client → Express API: calls API
- Express API → Auth Routes: mounts routes (evidence: `server/src/index.ts`)
- Auth Routes → Auth Controller: dispatches (evidence: `server/src/routes/auth.ts`)
- Auth Routes → Auth Guard: guards requests (evidence: `server/src/routes/auth.ts`)
- Auth Controller → Prisma Client: reads and writes (evidence: `server/src/controllers/auth.controller.ts`)
- Auth Controller → JWT and Tokens: issues tokens (evidence: `server/src/controllers/auth.controller.ts`)
- Auth Guard → JWT and Tokens: verifies tokens (evidence: `server/src/middleware/auth.middleware.ts`)
- Auth Controller → Verification Email: sends verification (evidence: `server/src/controllers/auth.controller.ts`)
- Verification Email → Brevo Email: delivers email
- Customer → Storefront UI: manages cart
- Storefront UI → API Client: requests commerce
- Express API → Cart Controller: routes cart
- Express API → Order Controller: routes orders
- Express API → Address Controller: routes addresses
- Order Controller → Prisma Client: creates and reads orders (evidence: `server/src/controllers/orders.controller.ts`)
- Order Controller → Order Formatting: formats orders (evidence: `server/src/controllers/orders.controller.ts`)
- Address Controller → Prisma Client: manages addresses (evidence: `server/src/controllers/addresses.controller.ts`)
- Prisma Client → PostgreSQL: persists records (evidence: `server/src/config/db.ts`)
- Administrator → Admin Pages: manages marketplace
- Admin Pages → Admin API Clients: requests admin data
- Admin API Clients → Express API: calls API
- Express API → Product Admin: routes product admin
- Express API → Category Admin: routes category admin
- Express API → Order Admin: routes order admin
- Express API → Customer Admin: routes customer admin
- Product Admin → Prisma Client: manages products (evidence: `server/src/controllers/admin-products.controller.ts`)
- Product Admin → Supabase Storage: uploads images (evidence: `server/src/controllers/admin-products.controller.ts`)
- Customer Admin → Prisma Client: manages customers (evidence: `server/src/controllers/admin-customers.controller.ts`)