agodse21/e-commerce-project

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