How newton122/ecommerce-website works
Purpose and Runtime Topology
This is an e-commerce system with a TypeScript storefront/admin UI and a separate Node.js backend. The repository contains two frontend structures: a Next.js App Router surface at app/page.tsx and app/[...slug]/page.tsx, plus a SPA-style application under src/app/App.tsx and src/app/AppRouter.tsx. The active frontend build/runtime should be confirmed because both next.config.ts and vite.config.ts exist.
Frontend Entry and Routing
The Next.js shell provides root layout, error/not-found handling, catch-all rendering, and sitemap generation through app/layout.tsx, app/[...slug]/page.tsx, and app/sitemap.xml/route.ts. The alternate SPA router centrally maps storefront, account, and admin pages in src/app/AppRouter.tsx; major routes include product browsing, checkout, profile, orders, and administration under src/app/pages/.
Client Application State
Cross-page client state is organized as React contexts for identity, cart, notifications, promotions, theme, and analytics: src/app/context/AuthContext.tsx, src/app/context/CartContext.tsx, and src/app/context/NotificationContext.tsx. These are the primary boundary between page/component UI and backend-backed user/session data. Authentication-gated behavior is concentrated in src/app/hooks/useRequireAuth.ts.
Commerce and Catalog Experience
Storefront flows span catalog discovery, collections, product detail, cart, and checkout. Core page-level components are src/app/pages/Shop.tsx, src/app/pages/ProductDetail.tsx, src/app/pages/Cart.tsx, and src/app/pages/Checkout.tsx; reusable product presentation is in src/app/components/ProductCard.tsx. Collection marketing and navigation are represented by src/app/pages/Collections.tsx, src/app/pages/CollectionDetail.tsx, and src/app/components/CollectionCTA.tsx.
Backend HTTP API
The backend is a separate TypeScript Node service rooted at blackphics-backend/src/server.ts. Route modules expose resource boundaries for authentication, products, carts, orders, profiles, collections, promos, reviews, uploads, users, design requests, and notifications; examples include blackphics-backend/src/routes/auth.routes.ts, blackphics-backend/src/routes/products.routes.ts, and blackphics-backend/src/routes/orders.routes.ts. Routes delegate to controllers, separating HTTP wiring from application operations, e.g. blackphics-backend/src/controllers/cart.controller.ts and blackphics-backend/src/controllers/products-write.controller.ts.
Authorization and Operational Boundaries
Backend authentication/authorization is middleware-driven via blackphics-backend/src/middleware/auth.ts, with async error propagation in blackphics-backend/src/middleware/asyncHandler.ts. Write APIs are explicitly separated for products and orders (blackphics-backend/src/routes/products-write.routes.ts, blackphics-backend/src/routes/orders-write.routes.ts), aligning with distinct admin UI pages such as src/app/pages/AdminProducts.tsx and src/app/pages/AdminOrders.tsx.
Persistence, Assets, and External Dependencies
Persistence uses Prisma, with a shared client at blackphics-backend/src/lib/prisma.ts, schema at blackphics-backend/prisma/schema.prisma, and versioned SQL migrations under blackphics-backend/prisma/migrations/. The schema evolution indicates persisted users/roles, products with soft deletion, collections, reviews, design requests/notes, and notifications. Uploads cross an API boundary through blackphics-backend/src/routes/upload.routes.ts and blackphics-backend/src/controllers/upload.controller.ts; no cloud storage, payment provider, or other external service is identifiable from the supplied tree.
Primary Flow
A user enters through Next or SPA routing, navigates catalog and collection pages, and uses client contexts to retain auth/cart/UI state. Client actions call backend REST-like route groups; middleware authenticates protected calls, controllers execute domain operations, and Prisma reads/writes the database. Admin interfaces use the same backend boundaries for product, order, user, design-request, and analytics operations.
Main entry points: AppRouter.tsx SPA router · products.routes.ts Resource routes · cart.controller.ts Domain controllers · products-write.routes.ts Admin write routes
Components 19
Next.js surface
App Router entry surface.
- Root layout
app/layout.tsx - Catch-all pages · Renders routed storefront paths.
app/[...slug]/page.tsx - Sitemap
app/sitemap.xml/route.ts
SPA application
Alternate Vite-style client application.
- SPA entry
src/app/App.tsx - SPA router · Maps storefront, account, and admin pages.
src/app/AppRouter.tsx - Client contexts · Auth, cart, and notification state cross page boundaries.
src/app/context/AuthContext.tsx - Auth guard · Gates authenticated client behavior.
src/app/hooks/useRequireAuth.ts - Catalog and checkout · Product discovery, detail, cart, and checkout flow.
src/app/pages/Shop.tsx - Collections · Collection marketing and detail pages.
src/app/pages/Collections.tsx - Admin operations · Product and order management UI.
src/app/pages/AdminProducts.tsx
Node backend
REST-like commerce API.
- API server · Backend service entry point.
blackphics-backend/src/server.ts - Resource routes · Auth, commerce, profile, collection, upload, and notification endpoints.
blackphics-backend/src/routes/products.routes.ts - Admin write routes · Separate product and order mutation boundaries.
blackphics-backend/src/routes/products-write.routes.ts - Authorization · Authenticates protected API calls.
blackphics-backend/src/middleware/auth.ts - Domain controllers · Execute cart, catalog, order, and upload operations.
blackphics-backend/src/controllers/cart.controller.ts - Upload handling · Receives asset uploads through the backend.
blackphics-backend/src/routes/upload.routes.ts
Persistence
- Prisma client · Shared persistence client.
blackphics-backend/src/lib/prisma.ts - Data schema · Models users, roles, products, collections, reviews, requests, and notifications.
blackphics-backend/prisma/schema.prisma - Application database
Connections 25
- Root layout → Catch-all pages: hosts
- Catch-all pages → SPA router: alternate client surface
- SPA entry → SPA router: boots
- SPA router → Catalog and checkout: routes to
- SPA router → Collections: routes to
- SPA router → Admin operations: routes to
- Catalog and checkout → Client contexts: uses
- Collections → Client contexts: uses
- Admin operations → Auth guard: requires
- Auth guard → Client contexts: reads identity
- Catalog and checkout → Resource routes: API calls
- Collections → Resource routes: API calls
- Admin operations → Admin write routes: admin mutations
- API server → Resource routes: mounts
- API server → Admin write routes: mounts
- Resource routes → Authorization: protects calls
- Admin write routes → Authorization: protects calls
- Authorization → Domain controllers: authorizes
- Resource routes → Domain controllers: delegates
- Admin write routes → Domain controllers: delegates
- Upload handling → Domain controllers: delegates
- Domain controllers → Prisma client: reads and writes
- Prisma client → Application database: connects
- Data schema → Prisma client: defines models
- Sitemap → Catch-all pages: indexes routes