burakorkmez/northwind-store

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