# burakorkmez/northwind-store architecture

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

- Interactive diagram: https://gitdiagram.com/burakorkmez/northwind-store
- Repository: https://github.com/burakorkmez/northwind-store

## Overview

#### Purpose and entry points
This is a PERN e-commerce platform: React SPA frontend, Express/TypeScript API, PostgreSQL persistence, authenticated checkout/orders, admin product management, and order-scoped Stream chat/video support. Backend startup is `backend/src/index.ts`; the browser entry and route composition begin at `frontend/src/main.jsx` and `frontend/src/App.jsx`.

#### Client application
The Vite React client renders catalog, product, cart, checkout return, order, admin, chat, and video views. Page-specific hooks own server-state interactions and view orchestration, while a client cart store holds shopping-cart state. API access is centralized in `frontend/src/lib/api.js`.
- `frontend/src/App.jsx`
- `frontend/src/hooks/useCartPage.js`
- `frontend/src/store/cart.js`

#### API and HTTP boundary
Express routers partition the API by business domain; controllers implement request handling for products, checkout, orders, administration, and Stream tokens/channel setup. The frontend reaches this boundary through its configured backend URL rather than directly accessing PostgreSQL or payment APIs.
- `backend/src/routes/productRouter.ts`
- `backend/src/routes/chekoutRouter.ts`
- `backend/src/controllers/orderController.ts`

#### Persistence and domain model
PostgreSQL, hosted on Neon, is accessed through Drizzle. The schema is the authoritative persistence boundary for users, products, orders, and related commerce state; a seed script supports initial data.
- `backend/src/db/index.ts`
- `backend/src/db/schema.ts`
- `backend/scripts/seed.ts`

#### Identity, authorization, and user lifecycle
Clerk authenticates users. Request middleware connects Clerk identity to backend/Sentry context, role utilities gate administrative operations, and the Clerk webhook synchronizes lifecycle changes into local persistence.
- `backend/src/middleware/sentryClerkUser.ts`
- `backend/src/lib/roles.ts`
- `backend/src/webhooks/clerk.ts`

#### Commerce and payment flow
Users browse products, retain a client cart, initiate checkout through the backend’s Polar integration, then return to an order/checkout UI. Polar webhooks are the server-side confirmation boundary for payment events and order state rather than trusting browser redirects.
- `backend/src/controllers/checkoutController.ts`
- `backend/src/lib/polar.ts`
- `backend/src/webhooks/polar.ts`

#### Media and customer-support collaboration
ImageKit provides product/media upload and delivery integration. Stream powers real-time order customer-support chat and video, with backend code handling privileged integration operations and frontend order views consuming the resulting experience.
- `backend/src/lib/imagekit.ts`
- `backend/src/lib/stream.ts`
- `frontend/src/pages/OrderChatPage.jsx`
- `frontend/src/pages/OrderVideoPage.jsx`

#### Operations and deployment
Sentry instrumentation/error UX spans backend and frontend. Backend environment validation and cron work centralize runtime operational concerns. The repository includes a Dockerfile for containerized deployment; required external infrastructure is Neon/PostgreSQL, Clerk, Polar, Stream, ImageKit, and Sentry.
- `backend/src/instrument.ts`
- `backend/src/lib/env.ts`
- `backend/src/lib/cron.ts`
- `Dockerfile`

Main entry points: [`backend/src/routes/productRouter.ts`](https://github.com/burakorkmez/northwind-store/blob/master/backend/src/routes/productRouter.ts) (Commerce routers), [`backend/src/db/schema.ts`](https://github.com/burakorkmez/northwind-store/blob/master/backend/src/db/schema.ts) (Commerce schema), [`frontend/src/App.jsx`](https://github.com/burakorkmez/northwind-store/blob/master/frontend/src/App.jsx) (SPA entry & routes), [`backend/src/index.ts`](https://github.com/burakorkmez/northwind-store/blob/master/backend/src/index.ts) (API startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React client"]
  node_client_entry["SPA entry &amp; routes<br/>React application<br/>[App.jsx]"]
  node_client_cart["Cart store<br/>client state<br/>[cart.js]"]
  node_client_cart_hook["Cart page orchestration<br/>React hook<br/>[useCartPage.js]"]
  node_client_api["API client<br/>HTTP client<br/>[api.js]"]
  node_client_chat["Order chat view<br/>React page<br/>[OrderChatPage.jsx]"]
  node_client_video["Order video view<br/>React page<br/>[OrderVideoPage.jsx]"]
end

subgraph group_backend["Express API"]
  node_api_startup["API startup<br/>Express bootstrap<br/>[index.ts]"]
  node_api_routes["Commerce routers<br/>Express routes<br/>[productRouter.ts]"]
  node_order_controller["Order controller<br/>request controller<br/>[orderController.ts]"]
  node_checkout_controller["Checkout controller<br/>request controller"]
  node_auth_roles["Identity &amp; admin roles<br/>auth middleware<br/>[sentryClerkUser.ts]"]
  node_clerk_webhook["Clerk lifecycle webhook<br/>webhook handler<br/>[clerk.ts]"]
  node_polar_webhook["Polar payment webhook<br/>webhook handler<br/>[polar.ts]"]
  node_db_schema["Commerce schema<br/>Drizzle schema<br/>[schema.ts]"]
end

subgraph group_external["External services"]
  node_database[("Neon PostgreSQL<br/>database")]
  node_clerk["Clerk<br/>identity provider"]
  node_polar["Polar<br/>payments"]
  node_stream["Stream<br/>chat and video"]
  node_media["ImageKit<br/>media service"]
  node_observability["Sentry<br/>observability"]
end

node_client_entry -->|"renders cart"| node_client_cart_hook
node_client_cart_hook -->|"reads and updates"| node_client_cart
node_client_entry -->|"uses"| node_client_api
node_client_api -->|"HTTPS API"| node_api_routes
node_api_startup -->|"mounts"| node_api_routes
node_api_routes -->|"checkout requests"| node_checkout_controller
node_api_routes -->|"order requests"| node_order_controller
node_auth_roles -->|"authenticates and authorizes"| node_api_routes
node_checkout_controller -->|"creates checkout"| node_polar
node_polar -->|"payment events"| node_polar_webhook
node_polar_webhook -->|"updates order state"| node_db_schema
node_order_controller -->|"reads and writes orders"| node_db_schema
node_api_routes -->|"product and admin data"| node_db_schema
node_db_schema -->|"Drizzle persistence"| node_database
node_clerk -->|"request identity"| node_auth_roles
node_clerk -->|"lifecycle events"| node_clerk_webhook
node_clerk_webhook -->|"syncs users"| node_db_schema
node_client_chat -->|"order support chat"| node_stream
node_client_video -->|"order support video"| node_stream
node_api_routes -->|"privileged tokens and channels"| node_stream
node_api_routes -->|"product media integration"| node_media
node_api_startup -->|"backend instrumentation"| node_observability
node_client_entry -->|"frontend error UX"| node_observability

click node_client_entry "https://github.com/burakorkmez/northwind-store/blob/master/frontend/src/App.jsx"
click node_client_cart "https://github.com/burakorkmez/northwind-store/blob/master/frontend/src/store/cart.js"
click node_client_cart_hook "https://github.com/burakorkmez/northwind-store/blob/master/frontend/src/hooks/useCartPage.js"
click node_client_api "https://github.com/burakorkmez/northwind-store/blob/master/frontend/src/lib/api.js"
click node_client_chat "https://github.com/burakorkmez/northwind-store/blob/master/frontend/src/pages/OrderChatPage.jsx"
click node_client_video "https://github.com/burakorkmez/northwind-store/blob/master/frontend/src/pages/OrderVideoPage.jsx"
click node_api_startup "https://github.com/burakorkmez/northwind-store/blob/master/backend/src/index.ts"
click node_api_routes "https://github.com/burakorkmez/northwind-store/blob/master/backend/src/routes/productRouter.ts"
click node_order_controller "https://github.com/burakorkmez/northwind-store/blob/master/backend/src/controllers/orderController.ts"
click node_checkout_controller "https://github.com/burakorkmez/northwind-store/blob/master/backend/src/controllers/checkoutController.ts"
click node_auth_roles "https://github.com/burakorkmez/northwind-store/blob/master/backend/src/middleware/sentryClerkUser.ts"
click node_clerk_webhook "https://github.com/burakorkmez/northwind-store/blob/master/backend/src/webhooks/clerk.ts"
click node_polar_webhook "https://github.com/burakorkmez/northwind-store/blob/master/backend/src/webhooks/polar.ts"
click node_db_schema "https://github.com/burakorkmez/northwind-store/blob/master/backend/src/db/schema.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_client_entry,node_client_cart,node_client_cart_hook,node_client_api,node_client_chat,node_client_video toneBlue
class node_api_startup,node_api_routes,node_order_controller,node_checkout_controller,node_auth_roles,node_clerk_webhook,node_polar_webhook,node_db_schema toneAmber
class node_database,node_clerk,node_polar,node_stream,node_media,node_observability toneMint
```

## Components

### React client

- [SPA entry & routes](https://github.com/burakorkmez/northwind-store/blob/master/frontend/src/App.jsx): React application · Composes catalog, cart, checkout, order, admin, chat, and video views. · `frontend/src/App.jsx`
- [Cart store](https://github.com/burakorkmez/northwind-store/blob/master/frontend/src/store/cart.js): client state · `frontend/src/store/cart.js`
- [Cart page orchestration](https://github.com/burakorkmez/northwind-store/blob/master/frontend/src/hooks/useCartPage.js): React hook · `frontend/src/hooks/useCartPage.js`
- [API client](https://github.com/burakorkmez/northwind-store/blob/master/frontend/src/lib/api.js): HTTP client · Uses the configured backend URL. · `frontend/src/lib/api.js`
- [Order chat view](https://github.com/burakorkmez/northwind-store/blob/master/frontend/src/pages/OrderChatPage.jsx): React page · `frontend/src/pages/OrderChatPage.jsx`
- [Order video view](https://github.com/burakorkmez/northwind-store/blob/master/frontend/src/pages/OrderVideoPage.jsx): React page · `frontend/src/pages/OrderVideoPage.jsx`

### Express API

- [API startup](https://github.com/burakorkmez/northwind-store/blob/master/backend/src/index.ts): Express bootstrap · `backend/src/index.ts`
- [Commerce routers](https://github.com/burakorkmez/northwind-store/blob/master/backend/src/routes/productRouter.ts): Express routes · Partitions product and checkout API endpoints. · `backend/src/routes/productRouter.ts`
- [Order controller](https://github.com/burakorkmez/northwind-store/blob/master/backend/src/controllers/orderController.ts): request controller · `backend/src/controllers/orderController.ts`
- [Checkout controller](https://github.com/burakorkmez/northwind-store/blob/master/backend/src/controllers/checkoutController.ts): request controller · `backend/src/controllers/checkoutController.ts`
- [Identity & admin roles](https://github.com/burakorkmez/northwind-store/blob/master/backend/src/middleware/sentryClerkUser.ts): auth middleware · Clerk identity is attached to requests and roles gate administration. · `backend/src/middleware/sentryClerkUser.ts`
- [Clerk lifecycle webhook](https://github.com/burakorkmez/northwind-store/blob/master/backend/src/webhooks/clerk.ts): webhook handler · Synchronizes user lifecycle changes locally. · `backend/src/webhooks/clerk.ts`
- [Polar payment webhook](https://github.com/burakorkmez/northwind-store/blob/master/backend/src/webhooks/polar.ts): webhook handler · Confirms payment events and order state server-side. · `backend/src/webhooks/polar.ts`
- [Commerce schema](https://github.com/burakorkmez/northwind-store/blob/master/backend/src/db/schema.ts): Drizzle schema · Authoritative model for users, products, orders, and commerce state. · `backend/src/db/schema.ts`

### External services

- **Neon PostgreSQL**: database
- **Clerk**: identity provider
- **Polar**: payments
- **Stream**: chat and video
- **ImageKit**: media service
- **Sentry**: observability

## Connections

- SPA entry & routes → Cart page orchestration: renders cart
- Cart page orchestration → Cart store: reads and updates
- SPA entry & routes → API client: uses
- API client → Commerce routers: HTTPS API
- API startup → Commerce routers: mounts
- Commerce routers → Checkout controller: checkout requests
- Commerce routers → Order controller: order requests
- Identity & admin roles → Commerce routers: authenticates and authorizes
- Checkout controller → Polar: creates checkout
- Polar → Polar payment webhook: payment events
- Polar payment webhook → Commerce schema: updates order state
- Order controller → Commerce schema: reads and writes orders
- Commerce routers → Commerce schema: product and admin data
- Commerce schema → Neon PostgreSQL: Drizzle persistence
- Clerk → Identity & admin roles: request identity
- Clerk → Clerk lifecycle webhook: lifecycle events
- Clerk lifecycle webhook → Commerce schema: syncs users
- Order chat view → Stream: order support chat
- Order video view → Stream: order support video
- Commerce routers → Stream: privileged tokens and channels
- Commerce routers → ImageKit: product media integration
- API startup → Sentry: backend instrumentation
- SPA entry & routes → Sentry: frontend error UX