Ecommerce Storefront & Admin Console

A live clothing store you can browse, buy from, and operate — not a template with dead buttons.

Browse products with URL-persisted search, pick the exact size and color that is in stock, merge quantities in the cart, and check out in three steps while prices stay frozen server-side. Store staff get a real console alongside it.

Overview

This is the frontend half of a full-stack commerce platform. The backend — Custom Ecommerce Backend API — owns every business rule, 24 PostgreSQL tables, and 71 REST endpoints under /api/v1. This Next.js application is both the customer storefront and the operations console that drives it.

Everything on screen is backed by a real endpoint. Empty states, loading skeletons, 403s, 409s, and 429s are designed screens, not afterthoughts.

The Problem

A commerce frontend usually stops at the happy path — a product grid and a cart that never fails. Operating a store is harder:

• One product has many purchasable variants (black / medium, blue / large) with separate SKUs, prices, stock, and images.
• Cart, discounts, shipping, stock reservation, and order snapshots must be server-authoritative — the client cannot trust its own math.
• Store staff need daily rigor: edit catalog, adjust stock without overselling, advance orders through only legal transitions, and prove who did what in an audit trail.
• Session and CSRF security must work without ever exposing a credential to JavaScript.

The Solution

A Next.js App Router application that treats the API contract as law and surfaces it completely:

1. Same-origin by design — next.config.ts rewrites /api/v1/:path* to API_ORIGIN, so the httpOnly / SameSite=Lax session cookie stays first-party — no token in JavaScript, no CORS.
2. CSRF wired once — a shared Axios instance (withCredentials: true) fetches a csrf_token and attaches x-csrf-token to every mutating request. No component touches axios directly.
3. Server state discipline — TanStack Query caches keyed by full query params via a central queryKeys factory; Zustand is reserved for pure UI state (drawers/toasts).

Key Features

• Catalog that respects URLs — home, listing, and category pages with search, brand filter, sort, and pagination persisted in query params.
• Product detail that tells the truth — gallery, variant picker (color/size) with live availability and computed final_price, ordered images with is_primary.
• Cart that merges — merge-on-add quantities, live server-side pricing, update/remove/clear — backed by advisory-locked endpoints.
• Three-step checkout → POST /orders — select saved address, optional coupon, shipping settles automatically, single-transaction order with immutable snapshots.
• Orders & reviews — history with status timeline, detail with frozen prices; one review per user per product with direct-to-ImageKit image uploads.
• Account center — profile, password, email (emailed verification), phone (OTP), address book with per-type defaults, session devices (revoke one / revoke others), deletion.
• Admin console (/admin, probe-gated) — dashboard KPIs + super-admin P&L/coupon analytics, products/variants/images editor (signed ImageKit uploads), categories, inventory reserve/release, order queue with a legal transition matrix, customers, coupons, and an append-only audit trail.

User Experience

Customer: browse → product detail (pick variant) → cart (merge) → 3-step checkout → order history with timeline → review with images → account.

Admin: dashboard → products editor (create variant, ImageKit upload) → categories / inventory → order queue (advance only legal transitions) → customers / coupons / audit.

Architecture at a Glance

One rule: no component talks to the network directly except through the shared client.

• Interface — App Router route groups (storefront) / (auth) / admin, shadcn/ui v4, Tailwind v4 CSS-first theme.
• Client — features/<domain>/api.ts + hooks.ts + components/, lib/api/client.ts envelope unwrapping (Paginated<T>), lib/api/queryKeys.ts factory, <Money> for decimal strings, react-hook-form + Zod mirroring server validation.
• Platform — Vercel (storefront) → Render (API) → Neon (PostgreSQL); next.config.ts remotePatterns for ik.imagekit.io, security headers; probe-based admin detection (GET /admin/products 200 vs 403).

See Design Docs above once available — for now FRONTEND_PROMPT.md (§9–12) and tasks/index.md (T00–T30) are the authoritative specs alongside the backend's Architecture docs.

Tech Stack

What This Project Shows

Product sense — turns a full platform into real screens: not just a product grid, but an operations console with transition-matrix order flow, guarded inventory adjustments, coupon P&L, and an audit trail that proves who did what. Every empty, loading, and error state is designed.

Engineering care — same-origin session architecture with zero tokens in JavaScript, one CSRF-aware Axios layer, typed paginated envelopes (Paginated<T>), URL-persisted browsing state, and probe-based role detection with server re-enforcement.

Scope Notes

Honest limitations inherited from the API: payments are mock only (Paymob T19 / T-081…T-087 marked won't do); review purchase-verification is flag-gated off; /verify-email and /verify-email-change must persist (backend emails link there). No CI in this repo — quality gates are local lint → typecheck → test.

Links

• Backend: Custom Ecommerce Backend API — REST API, Prisma/PostgreSQL, docs/api/**
• Source lives at D:\code\client for ecommerce · Vercel auto-deploy on push to main