# agodse21/e-commerce-project architecture

> Architecture diagram of the GitHub repository agodse21/e-commerce-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/agodse21/e-commerce-project
- Repository: https://github.com/agodse21/e-commerce-project

## Overview

#### 1. Purpose and topology
Amazon-inspired e-commerce monorepo: product discovery, session-backed cart/wishlist, mocked checkout, and order history. The browser SPA communicates exclusively over `/api/*`; frontend and backend have no direct imports. Core deployment routes static SPA traffic and serverless API traffic through Vercel.
- `frontend/src/main.tsx`
- `backend/src/app.ts`
- `api/index.ts`
- `vercel.json`

#### 2. Frontend application and navigation
React/Vite SPA uses TanStack Router route groups to separate public shopping flows from authenticated-named account pages. The generated route tree is the router’s structural output. Public routes cover catalog, product detail, cart, checkout, and confirmation; account routes include orders and wishlist.
- `frontend/src/routes/__root.tsx`
- `frontend/src/routes/_public/route.tsx`
- `frontend/src/routes/_authenticated/route.tsx`
- `frontend/src/routeTree.gen.ts`

#### 3. Client data and UI state boundary
Route-level screens consume domain hooks, which use the API client and query caching for products, cart, orders, search suggestions, and wishlist. Zustand is intentionally limited to client UI state such as cart drawer behavior rather than becoming the server-state source of truth.
- `frontend/src/lib/api.ts`
- `frontend/src/hooks/useCart.ts`
- `frontend/src/hooks/useProducts.ts`
- `frontend/src/store/cartStore.ts`

#### 4. Commerce user flows
Catalog search/filter/sort leads to product detail and add-to-cart or Buy Now. Cart and checkout collect address data, create an order, then navigate to an order-specific confirmation; saved cart remains distinct from Buy Now. Wishlist operations are session scoped and rendered through dedicated components/routes.
- `frontend/src/routes/_public/products/$productId.tsx`
- `frontend/src/routes/_public/checkout.tsx`
- `frontend/src/routes/_public/order-confirmation/$orderId.tsx`
- `frontend/src/routes/_authenticated/wishlist.tsx`

#### 5. API layering and request pipeline
Express exposes domain routes, dispatches through controllers, and centralizes business/database behavior in services. Cross-cutting middleware establishes CORS, rate limiting, validation, error conversion, and the session identity before handlers execute. Responses cross the HTTP boundary as the contract consumed by frontend hooks.
- `backend/src/app.ts`
- `backend/src/routes/cart.ts`
- `backend/src/controllers/orderController.ts`
- `backend/src/services/orderService.ts`
- `backend/src/middleware/sessionMiddleware.ts`

#### 6. Persistence, sessions, and fulfillment
PostgreSQL is accessed only through Prisma. `amazon_session_id` cookie identity associates anonymous carts and wishlists across refreshes; authentication and payment are deliberately absent. Order creation persists checkout/order data and triggers confirmation delivery, with SMTP optional and server logging as fallback.
- `backend/prisma/schema.prisma`
- `backend/src/utils/prisma.ts`
- `backend/src/services/cartService.ts`
- `backend/src/services/wishlistService.ts`
- `backend/src/services/emailService.ts`

#### 7. Runtime and infrastructure
Local development runs Vite on 5173 and Express on 3001, with Vite proxying API calls; Docker Compose supplies local infrastructure. Production runs the shared Express app through the Vercel serverless entrypoint, backed by PostgreSQL/Neon. Prisma migrations and seed data initialize the catalog.
- `backend/src/server.ts`
- `docker-compose.yml`
- `backend/prisma/migrations/20260612133144_amazon_data/migration.sql`
- `backend/prisma/seed.ts`
- `.github/workflows/cd.yml`

Main entry points: [`backend/src/app.ts`](https://github.com/agodse21/e-commerce-project/blob/main/backend/src/app.ts) (Express app), [`frontend/src/routeTree.gen.ts`](https://github.com/agodse21/e-commerce-project/blob/main/frontend/src/routeTree.gen.ts) (Route tree), [`frontend/src/routes/_public/checkout.tsx`](https://github.com/agodse21/e-commerce-project/blob/main/frontend/src/routes/_public/checkout.tsx) (Product & checkout screens), [`backend/src/services/orderService.ts`](https://github.com/agodse21/e-commerce-project/blob/main/backend/src/services/orderService.ts) (Order service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React SPA"]
  node_spa["Vite React entry<br/>SPA bootstrap<br/>[main.tsx]"]
  node_router["Route tree<br/>TanStack Router<br/>[routeTree.gen.ts]"]
  node_public_routes["Shopping routes<br/>public route group<br/>[route.tsx]"]
  node_account_routes["Account routes<br/>account route group<br/>[route.tsx]"]
  node_commerce_screens["Product &amp; checkout screens<br/>route screens<br/>[checkout.tsx]"]
  node_domain_hooks["Domain hooks<br/>query hooks<br/>[useCart.ts]"]
  node_api_client["API client<br/>HTTP client<br/>[api.ts]"]
  node_ui_store["Cart drawer state<br/>Zustand UI state<br/>[cartStore.ts]"]
end

subgraph group_backend["Express API"]
  node_express_app["Express app<br/>API composition<br/>[app.ts]"]
  node_session_middleware["Session identity<br/>middleware"]
  node_cart_routes["Cart routes<br/>domain routes<br/>[cart.ts]"]
  node_order_controller["Order controller<br/>[orderController.ts]"]
  node_order_service["Order service<br/>business service<br/>[orderService.ts]"]
  node_commerce_services["Cart &amp; wishlist services<br/>business services<br/>[cartService.ts]"]
end

subgraph group_data["Data &amp; delivery"]
  node_prisma["Prisma access<br/>database client<br/>[prisma.ts]"]
  node_postgres[("PostgreSQL / Neon<br/>relational database<br/>[schema.prisma]")]
  node_confirmation["Confirmation delivery<br/>email service<br/>[emailService.ts]"]
  node_catalog_bootstrap["Catalog initialization<br/>Prisma migration &amp; seed<br/>[seed.ts]"]
end

subgraph group_runtime["Runtime &amp; deployment"]
  node_local_runtime["Local dev runtime<br/>[docker-compose.yml]"]
  node_vercel{{"Vercel deployment<br/>serverless hosting<br/>[vercel.json]"}}
  node_serverless_entry["Serverless API entry<br/>Vercel function<br/>[index.ts]"]
end

node_spa -->|"renders"| node_router
node_router -->|"selects"| node_public_routes
node_router -->|"selects"| node_account_routes
node_public_routes -->|"hosts"| node_commerce_screens
node_commerce_screens -->|"uses"| node_domain_hooks
node_account_routes -->|"uses"| node_domain_hooks
node_commerce_screens -->|"controls drawer"| node_ui_store
node_domain_hooks -->|"queries and mutates"| node_api_client
node_api_client -->|"/api HTTP"| node_express_app
node_express_app -->|"establishes identity"| node_session_middleware
node_express_app -->|"mounts"| node_cart_routes
node_express_app -->|"dispatches orders"| node_order_controller
node_cart_routes -->|"delegates"| node_commerce_services
node_order_controller -->|"delegates"| node_order_service
node_commerce_services -->|"persists through"| node_prisma
node_order_service -->|"persists through"| node_prisma
node_order_service -->|"triggers"| node_confirmation
node_prisma -->|"reads and writes"| node_postgres
node_catalog_bootstrap -->|"migrates and seeds"| node_postgres
node_local_runtime -.->|"serves Vite"| node_spa
node_local_runtime -.->|"runs Express"| node_express_app
node_vercel -->|"serves static app"| node_spa
node_vercel -->|"routes /api"| node_serverless_entry
node_serverless_entry -->|"loads shared app"| node_express_app

click node_spa "https://github.com/agodse21/e-commerce-project/blob/main/frontend/src/main.tsx"
click node_router "https://github.com/agodse21/e-commerce-project/blob/main/frontend/src/routeTree.gen.ts"
click node_public_routes "https://github.com/agodse21/e-commerce-project/blob/main/frontend/src/routes/_public/route.tsx"
click node_account_routes "https://github.com/agodse21/e-commerce-project/blob/main/frontend/src/routes/_authenticated/route.tsx"
click node_commerce_screens "https://github.com/agodse21/e-commerce-project/blob/main/frontend/src/routes/_public/checkout.tsx"
click node_domain_hooks "https://github.com/agodse21/e-commerce-project/blob/main/frontend/src/hooks/useCart.ts"
click node_api_client "https://github.com/agodse21/e-commerce-project/blob/main/frontend/src/lib/api.ts"
click node_ui_store "https://github.com/agodse21/e-commerce-project/blob/main/frontend/src/store/cartStore.ts"
click node_express_app "https://github.com/agodse21/e-commerce-project/blob/main/backend/src/app.ts"
click node_session_middleware "https://github.com/agodse21/e-commerce-project/blob/main/backend/src/middleware/sessionMiddleware.ts"
click node_cart_routes "https://github.com/agodse21/e-commerce-project/blob/main/backend/src/routes/cart.ts"
click node_order_controller "https://github.com/agodse21/e-commerce-project/blob/main/backend/src/controllers/orderController.ts"
click node_order_service "https://github.com/agodse21/e-commerce-project/blob/main/backend/src/services/orderService.ts"
click node_commerce_services "https://github.com/agodse21/e-commerce-project/blob/main/backend/src/services/cartService.ts"
click node_prisma "https://github.com/agodse21/e-commerce-project/blob/main/backend/src/utils/prisma.ts"
click node_postgres "https://github.com/agodse21/e-commerce-project/blob/main/backend/prisma/schema.prisma"
click node_confirmation "https://github.com/agodse21/e-commerce-project/blob/main/backend/src/services/emailService.ts"
click node_local_runtime "https://github.com/agodse21/e-commerce-project/blob/main/docker-compose.yml"
click node_vercel "https://github.com/agodse21/e-commerce-project/blob/main/vercel.json"
click node_serverless_entry "https://github.com/agodse21/e-commerce-project/blob/main/api/index.ts"
click node_catalog_bootstrap "https://github.com/agodse21/e-commerce-project/blob/main/backend/prisma/seed.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_spa,node_router,node_public_routes,node_account_routes,node_commerce_screens,node_domain_hooks,node_api_client,node_ui_store toneBlue
class node_express_app,node_session_middleware,node_cart_routes,node_order_controller,node_order_service,node_commerce_services toneAmber
class node_prisma,node_postgres,node_confirmation,node_catalog_bootstrap toneMint
class node_local_runtime,node_vercel,node_serverless_entry toneRose
```

## Components

### React SPA

- [Vite React entry](https://github.com/agodse21/e-commerce-project/blob/main/frontend/src/main.tsx): SPA bootstrap · `frontend/src/main.tsx`
- [Route tree](https://github.com/agodse21/e-commerce-project/blob/main/frontend/src/routeTree.gen.ts): TanStack Router · Separates public shopping and account-named route groups. · `frontend/src/routeTree.gen.ts`
- [Shopping routes](https://github.com/agodse21/e-commerce-project/blob/main/frontend/src/routes/_public/route.tsx): public route group · Catalog, product, cart, checkout, and confirmation flows. · `frontend/src/routes/_public/route.tsx`
- [Account routes](https://github.com/agodse21/e-commerce-project/blob/main/frontend/src/routes/_authenticated/route.tsx): account route group · Hosts session-scoped orders and wishlist views. · `frontend/src/routes/_authenticated/route.tsx`
- [Product & checkout screens](https://github.com/agodse21/e-commerce-project/blob/main/frontend/src/routes/_public/checkout.tsx): route screens · Product detail adds to cart or Buy Now; checkout creates orders. · `frontend/src/routes/_public/checkout.tsx`
- [Domain hooks](https://github.com/agodse21/e-commerce-project/blob/main/frontend/src/hooks/useCart.ts): query hooks · Own server state for products, cart, orders, search, and wishlist. · `frontend/src/hooks/useCart.ts`
- [API client](https://github.com/agodse21/e-commerce-project/blob/main/frontend/src/lib/api.ts): HTTP client · The SPA's exclusive backend boundary under /api/*. · `frontend/src/lib/api.ts`
- [Cart drawer state](https://github.com/agodse21/e-commerce-project/blob/main/frontend/src/store/cartStore.ts): Zustand UI state · Limited to client UI state, not server state. · `frontend/src/store/cartStore.ts`

### Express API

- [Express app](https://github.com/agodse21/e-commerce-project/blob/main/backend/src/app.ts): API composition · Applies cross-cutting middleware and mounts domain routes. · `backend/src/app.ts`
- [Session identity](https://github.com/agodse21/e-commerce-project/blob/main/backend/src/middleware/sessionMiddleware.ts): middleware · Maps amazon_session_id cookie to anonymous identity. · `backend/src/middleware/sessionMiddleware.ts`
- [Cart routes](https://github.com/agodse21/e-commerce-project/blob/main/backend/src/routes/cart.ts): domain routes · Dispatch cart requests into the API layers. · `backend/src/routes/cart.ts`
- [Order controller](https://github.com/agodse21/e-commerce-project/blob/main/backend/src/controllers/orderController.ts): controller · Handles order creation requests. · `backend/src/controllers/orderController.ts`
- [Order service](https://github.com/agodse21/e-commerce-project/blob/main/backend/src/services/orderService.ts): business service · Persists checkout data and triggers confirmation delivery. · `backend/src/services/orderService.ts`
- [Cart & wishlist services](https://github.com/agodse21/e-commerce-project/blob/main/backend/src/services/cartService.ts): business services · Session-scoped cart and wishlist persistence. · `backend/src/services/cartService.ts`

### Data & delivery

- [Prisma access](https://github.com/agodse21/e-commerce-project/blob/main/backend/src/utils/prisma.ts): database client · The sole PostgreSQL access boundary. · `backend/src/utils/prisma.ts`
- [PostgreSQL / Neon](https://github.com/agodse21/e-commerce-project/blob/main/backend/prisma/schema.prisma): relational database · Stores catalog, carts, wishlists, orders, and checkout data. · `backend/prisma/schema.prisma`
- [Confirmation delivery](https://github.com/agodse21/e-commerce-project/blob/main/backend/src/services/emailService.ts): email service · Uses optional SMTP, falling back to server logging. · `backend/src/services/emailService.ts`
- [Catalog initialization](https://github.com/agodse21/e-commerce-project/blob/main/backend/prisma/seed.ts): Prisma migration & seed · Initializes schema and catalog data. · `backend/prisma/seed.ts`

### Runtime & deployment

- [Local dev runtime](https://github.com/agodse21/e-commerce-project/blob/main/docker-compose.yml): Vite + Express + Compose · Vite proxies API calls to Express; Compose supplies local infrastructure. · `docker-compose.yml`
- [Vercel deployment](https://github.com/agodse21/e-commerce-project/blob/main/vercel.json): serverless hosting · Routes static SPA and /api traffic to the shared Express app. · `vercel.json`
- [Serverless API entry](https://github.com/agodse21/e-commerce-project/blob/main/api/index.ts): Vercel function · Runs the shared Express application in production. · `api/index.ts`

## Connections

- Vite React entry → Route tree: renders
- Route tree → Shopping routes: selects
- Route tree → Account routes: selects
- Shopping routes → Product & checkout screens: hosts
- Product & checkout screens → Domain hooks: uses
- Account routes → Domain hooks: uses
- Product & checkout screens → Cart drawer state: controls drawer
- Domain hooks → API client: queries and mutates
- API client → Express app: /api HTTP
- Express app → Session identity: establishes identity
- Express app → Cart routes: mounts
- Express app → Order controller: dispatches orders
- Cart routes → Cart & wishlist services: delegates
- Order controller → Order service: delegates
- Cart & wishlist services → Prisma access: persists through
- Order service → Prisma access: persists through
- Order service → Confirmation delivery: triggers
- Prisma access → PostgreSQL / Neon: reads and writes
- Catalog initialization → PostgreSQL / Neon: migrates and seeds
- Local dev runtime → Vite React entry: serves Vite
- Local dev runtime → Express app: runs Express
- Vercel deployment → Vite React entry: serves static app
- Vercel deployment → Serverless API entry: routes /api
- Serverless API entry → Express app: loads shared app