# newton122/ecommerce-website architecture

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

- Interactive diagram: https://gitdiagram.com/newton122/ecommerce-website
- Repository: https://github.com/newton122/ecommerce-website

## Overview

#### 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: [`src/app/AppRouter.tsx`](https://github.com/newton122/ecommerce-website/blob/main/src/app/AppRouter.tsx) (SPA router), [`blackphics-backend/src/routes/products.routes.ts`](https://github.com/newton122/ecommerce-website/blob/main/blackphics-backend/src/routes/products.routes.ts) (Resource routes), [`blackphics-backend/src/controllers/cart.controller.ts`](https://github.com/newton122/ecommerce-website/blob/main/blackphics-backend/src/controllers/cart.controller.ts) (Domain controllers), [`blackphics-backend/src/routes/products-write.routes.ts`](https://github.com/newton122/ecommerce-website/blob/main/blackphics-backend/src/routes/products-write.routes.ts) (Admin write routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_next["Next.js surface"]
  node_next_layout["Root layout<br/>Next layout<br/>[layout.tsx]"]
  node_next_catchall["Catch-all pages<br/>Next route<br/>[page.tsx]"]
  node_next_sitemap["Sitemap<br/>Next route handler<br/>[route.ts]"]
end

subgraph group_spa["SPA application"]
  node_spa_entry["SPA entry<br/>React app<br/>[App.tsx]"]
  node_spa_router["SPA router<br/>React router<br/>[AppRouter.tsx]"]
  node_client_state["Client contexts<br/>React state<br/>[AuthContext.tsx]"]
  node_auth_guard["Auth guard<br/>React hook<br/>[useRequireAuth.ts]"]
  node_storefront["Catalog and checkout<br/>Commerce pages<br/>[Shop.tsx]"]
  node_collections["Collections<br/>Commerce pages<br/>[Collections.tsx]"]
  node_admin_ui["Admin operations<br/>Admin pages<br/>[AdminProducts.tsx]"]
end

subgraph group_backend["Node backend"]
  node_api_server{{"API server<br/>Node server<br/>[server.ts]"}}
  node_api_routes["Resource routes<br/>HTTP routes<br/>[products.routes.ts]"]
  node_write_routes["Admin write routes<br/>HTTP routes"]
  node_auth_middleware["Authorization<br/>Express middleware<br/>[auth.ts]"]
  node_controllers["Domain controllers<br/>[cart.controller.ts]"]
  node_uploads["Upload handling<br/>Upload API<br/>[upload.routes.ts]"]
end

subgraph group_data["Persistence"]
  node_prisma_client["Prisma client<br/>ORM<br/>[prisma.ts]"]
  node_prisma_schema["Data schema<br/>Prisma schema<br/>[schema.prisma]"]
  node_database[("Application database<br/>Relational database")]
end

node_next_layout -->|"hosts"| node_next_catchall
node_next_catchall -.->|"alternate client surface"| node_spa_router
node_spa_entry -->|"boots"| node_spa_router
node_spa_router -->|"routes to"| node_storefront
node_spa_router -->|"routes to"| node_collections
node_spa_router -->|"routes to"| node_admin_ui
node_storefront -->|"uses"| node_client_state
node_collections -->|"uses"| node_client_state
node_admin_ui -->|"requires"| node_auth_guard
node_auth_guard -->|"reads identity"| node_client_state
node_storefront -->|"API calls"| node_api_routes
node_collections -->|"API calls"| node_api_routes
node_admin_ui -->|"admin mutations"| node_write_routes
node_api_server -->|"mounts"| node_api_routes
node_api_server -->|"mounts"| node_write_routes
node_api_routes -->|"protects calls"| node_auth_middleware
node_write_routes -->|"protects calls"| node_auth_middleware
node_auth_middleware -->|"authorizes"| node_controllers
node_api_routes -->|"delegates"| node_controllers
node_write_routes -->|"delegates"| node_controllers
node_uploads -->|"delegates"| node_controllers
node_controllers -->|"reads and writes"| node_prisma_client
node_prisma_client -->|"connects"| node_database
node_prisma_schema -.->|"defines models"| node_prisma_client
node_next_sitemap -.->|"indexes routes"| node_next_catchall

click node_next_layout "https://github.com/newton122/ecommerce-website/blob/main/app/layout.tsx"
click node_next_catchall "https://github.com/newton122/ecommerce-website/blob/main/app/%5B...slug%5D/page.tsx"
click node_next_sitemap "https://github.com/newton122/ecommerce-website/blob/main/app/sitemap.xml/route.ts"
click node_spa_entry "https://github.com/newton122/ecommerce-website/blob/main/src/app/App.tsx"
click node_spa_router "https://github.com/newton122/ecommerce-website/blob/main/src/app/AppRouter.tsx"
click node_client_state "https://github.com/newton122/ecommerce-website/blob/main/src/app/context/AuthContext.tsx"
click node_auth_guard "https://github.com/newton122/ecommerce-website/blob/main/src/app/hooks/useRequireAuth.ts"
click node_storefront "https://github.com/newton122/ecommerce-website/blob/main/src/app/pages/Shop.tsx"
click node_collections "https://github.com/newton122/ecommerce-website/blob/main/src/app/pages/Collections.tsx"
click node_admin_ui "https://github.com/newton122/ecommerce-website/blob/main/src/app/pages/AdminProducts.tsx"
click node_api_server "https://github.com/newton122/ecommerce-website/blob/main/blackphics-backend/src/server.ts"
click node_api_routes "https://github.com/newton122/ecommerce-website/blob/main/blackphics-backend/src/routes/products.routes.ts"
click node_write_routes "https://github.com/newton122/ecommerce-website/blob/main/blackphics-backend/src/routes/products-write.routes.ts"
click node_auth_middleware "https://github.com/newton122/ecommerce-website/blob/main/blackphics-backend/src/middleware/auth.ts"
click node_controllers "https://github.com/newton122/ecommerce-website/blob/main/blackphics-backend/src/controllers/cart.controller.ts"
click node_prisma_client "https://github.com/newton122/ecommerce-website/blob/main/blackphics-backend/src/lib/prisma.ts"
click node_prisma_schema "https://github.com/newton122/ecommerce-website/blob/main/blackphics-backend/prisma/schema.prisma"
click node_uploads "https://github.com/newton122/ecommerce-website/blob/main/blackphics-backend/src/routes/upload.routes.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_next_layout,node_next_catchall,node_next_sitemap toneBlue
class node_spa_entry,node_spa_router,node_client_state,node_auth_guard,node_storefront,node_collections,node_admin_ui toneAmber
class node_api_server,node_api_routes,node_write_routes,node_auth_middleware,node_controllers,node_uploads toneMint
class node_prisma_client,node_prisma_schema,node_database toneRose
```

## Components

### Next.js surface

App Router entry surface.

- [Root layout](https://github.com/newton122/ecommerce-website/blob/main/app/layout.tsx): Next layout · `app/layout.tsx`
- [Catch-all pages](https://github.com/newton122/ecommerce-website/blob/main/app/%5B...slug%5D/page.tsx): Next route · Renders routed storefront paths. · `app/[...slug]/page.tsx`
- [Sitemap](https://github.com/newton122/ecommerce-website/blob/main/app/sitemap.xml/route.ts): Next route handler · `app/sitemap.xml/route.ts`

### SPA application

Alternate Vite-style client application.

- [SPA entry](https://github.com/newton122/ecommerce-website/blob/main/src/app/App.tsx): React app · `src/app/App.tsx`
- [SPA router](https://github.com/newton122/ecommerce-website/blob/main/src/app/AppRouter.tsx): React router · Maps storefront, account, and admin pages. · `src/app/AppRouter.tsx`
- [Client contexts](https://github.com/newton122/ecommerce-website/blob/main/src/app/context/AuthContext.tsx): React state · Auth, cart, and notification state cross page boundaries. · `src/app/context/AuthContext.tsx`
- [Auth guard](https://github.com/newton122/ecommerce-website/blob/main/src/app/hooks/useRequireAuth.ts): React hook · Gates authenticated client behavior. · `src/app/hooks/useRequireAuth.ts`
- [Catalog and checkout](https://github.com/newton122/ecommerce-website/blob/main/src/app/pages/Shop.tsx): Commerce pages · Product discovery, detail, cart, and checkout flow. · `src/app/pages/Shop.tsx`
- [Collections](https://github.com/newton122/ecommerce-website/blob/main/src/app/pages/Collections.tsx): Commerce pages · Collection marketing and detail pages. · `src/app/pages/Collections.tsx`
- [Admin operations](https://github.com/newton122/ecommerce-website/blob/main/src/app/pages/AdminProducts.tsx): Admin pages · Product and order management UI. · `src/app/pages/AdminProducts.tsx`

### Node backend

REST-like commerce API.

- [API server](https://github.com/newton122/ecommerce-website/blob/main/blackphics-backend/src/server.ts): Node server · Backend service entry point. · `blackphics-backend/src/server.ts`
- [Resource routes](https://github.com/newton122/ecommerce-website/blob/main/blackphics-backend/src/routes/products.routes.ts): HTTP routes · Auth, commerce, profile, collection, upload, and notification endpoints. · `blackphics-backend/src/routes/products.routes.ts`
- [Admin write routes](https://github.com/newton122/ecommerce-website/blob/main/blackphics-backend/src/routes/products-write.routes.ts): HTTP routes · Separate product and order mutation boundaries. · `blackphics-backend/src/routes/products-write.routes.ts`
- [Authorization](https://github.com/newton122/ecommerce-website/blob/main/blackphics-backend/src/middleware/auth.ts): Express middleware · Authenticates protected API calls. · `blackphics-backend/src/middleware/auth.ts`
- [Domain controllers](https://github.com/newton122/ecommerce-website/blob/main/blackphics-backend/src/controllers/cart.controller.ts): Controllers · Execute cart, catalog, order, and upload operations. · `blackphics-backend/src/controllers/cart.controller.ts`
- [Upload handling](https://github.com/newton122/ecommerce-website/blob/main/blackphics-backend/src/routes/upload.routes.ts): Upload API · Receives asset uploads through the backend. · `blackphics-backend/src/routes/upload.routes.ts`

### Persistence

- [Prisma client](https://github.com/newton122/ecommerce-website/blob/main/blackphics-backend/src/lib/prisma.ts): ORM · Shared persistence client. · `blackphics-backend/src/lib/prisma.ts`
- [Data schema](https://github.com/newton122/ecommerce-website/blob/main/blackphics-backend/prisma/schema.prisma): Prisma schema · Models users, roles, products, collections, reviews, requests, and notifications. · `blackphics-backend/prisma/schema.prisma`
- **Application database**: Relational database

## Connections

- 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