CodeBook | E-Commerce Platform 1 – React, Vite, TypeScript, Express & PostgreSQL Full-Stack Project (including Storefront + Admin Panel + Role-Based Access Control + AI Business Insights & more)

A modern, full-stack e-commerce platform for selling computer science eBooks. It includes a complete customer storefront (catalog, cart, Stripe checkout, address book, orders, reviews, support tickets) and a full admin console (products, orders, users, analytics, AI business insights, review moderation, tickets, activity log). The live API is an Express + Prisma + PostgreSQL backend in backend/ (migrating away from the retired AWS Lambda + DynamoDB stack kept in aws-lambda/ for reference). The frontend is a React 19 + Vite + TypeScript SPA with TanStack Query, Tailwind CSS, and JWT/Google OAuth auth.

• Live demo (legacy AWS-backed showcase): https://codebook-aws.vercel.app/
• Security: private vulnerability reports → see SECURITY.md · contact@arnobmahmud.com
• Author: Arnob Mahmud · GitHub @arnobt78

Migration status (important for learners): we are moving off AWS Lambda/DynamoDB to the Express API in backend/. That new backend is not deployed to a public server yet, and the Vercel frontend is not cut over to it. Local development uses Vite + backend/ + Postgres. The public demo URL above still runs the older AWS-backed stack until Coolify/VPS + Vercel cutover is completed.

1. Project Overview
2. Architecture Overview
3. Key Features
4. Technology Stack
5. Project Structure
6. Prerequisites
7. Environment Variables
8. Installation & Local Run
9. Demo Accounts
10. Frontend Routes
11. Backend API Endpoints
12. How Core Pieces Work (Learner Guide)
13. Reusable Components & Patterns
14. Libraries & Dependencies (Short Lessons)
15. Optional: Launch with Diploi
16. Documentation Links
17. Keywords
18. Security
19. Contributing
20. Conclusion
21. License

CodeBook teaches real e-commerce patterns in a single readable codebase:

• Customer journey: browse → filter → cart → Stripe pay → order history / digital library
• Admin journey: inventory, orders, refunds/labels, users, reviews, tickets, analytics + AI insights
• Engineering patterns: strict TypeScript, Zod at API boundaries, TanStack Query invalidation (no full-page reloads), JWT + Google OAuth, Sentry tunneled through your own API

┌──────────────────────────────────────────────────────────────┐
│  Frontend — React 19 + Vite + TypeScript (SPA)               │
│  pages / components / hooks / services / context             │
│  TanStack Query 5 · Tailwind 3 · React Router 7              │
│  Local: http://localhost:3000                                │
│  Hosting target: Vercel (cutover to new API pending)         │
└────────────────────────────┬─────────────────────────────────┘
                             │ HTTPS / JSON + Bearer JWT
┌────────────────────────────▼─────────────────────────────────┐
│  Backend — Express + Prisma + PostgreSQL                     │
│  backend/src/{routes,services,lib}                           │
│  Local recommended: http://localhost:4000                    │
│  Deploy target: Coolify / Hetzner VPS (intentionally deferred)│
└────────────────────────────┬─────────────────────────────────┘
                             │
        ┌────────────────────┼────────────────────┐
        ▼                    ▼                    ▼
   Stripe / Brevo      Cloudinary / Shippo   Google OAuth / LLMs
   (payments/email)      (images/labels)      (sign-in / AI insights)

Reference only (not live): aws-lambda/  ← retired AWS Lambda + DynamoDB API

Response shape tip: routes return plain JSON (res.status(n).json(data)). Services hold business logic; Zod validates bodies at the route boundary before services run.

• Product catalog with search/filter/sort, featured products, product detail (QR, ratings, book metadata)
• Cart (persisted to localStorage) + Stripe Checkout
• Optional address book + shipping address snapshot on orders
• Dashboard order history + customer order detail with status timeline
• Product reviews (verified-purchase badge) + support tickets (priority/category/order link)
• Login / Register split-layout auth + one-click demo accounts + Continue with Google

• Dashboard KPI cards + analytics charts (Recharts)
• Products / Orders / Users / Reviews / Tickets CRUD with DataTable + detail pages
• Order status, tracking, Shippo label generation, Stripe refunds
• Review moderation + store reply (adminReply)
• Activity / management history log
• AI Business Insights (multi-provider free-tier LLM fallback)

• Role-based routes (user vs admin)
• Instant UI after mutations (TanStack Query invalidation — no location.reload())
• Admin code-split lazy chunk + idle prefetch for admins
• Sentry error monitoring via first-party tunnel POST /api/monitoring
• Invoice PDF attached to order-confirmation email (pdfkit + Brevo)

ecommerce-codebook/
├── src/                      # Vite React frontend
│   ├── pages/                # Route pages (Home, Products, Cart, Admin/*, …)
│   ├── components/
│   │   ├── ui/               # Reusable primitives (DataTable, forms, RippleButton, …)
│   │   ├── Elements/         # ProductCard, ReviewForm, Rating, …
│   │   ├── Layouts/          # Header, Footer, AdminLayout
│   │   └── Sections/         # Search and composed sections
│   ├── hooks/                # useProducts, useAdmin, useAuth, useTickets, …
│   ├── services/             # fetch wrappers per domain (+ apiError.ts)
│   ├── context/              # CartContext, FilterContext
│   ├── routes/               # AllRoutes.tsx, ProtectedRoute.tsx
│   ├── lib/                  # apiBase.ts, toast.ts, sentry.ts
│   ├── utils/                # queryInvalidation helpers, export utils
│   ├── reducers/             # Cart / filter reducers
│   └── types/                # Shared frontend DTOs
├── backend/                  # Live Express API
│   ├── src/
│   │   ├── app.ts            # Middleware + route mounts
│   │   ├── server.ts         # listen(PORT)
│   │   ├── routes/           # HTTP endpoints
│   │   ├── services/         # Business logic + Prisma
│   │   └── lib/              # auth, rateLimit, ai/, sentry, …
│   ├── prisma/
│   │   ├── schema.prisma
│   │   └── seed.ts           # Seeds from ../data/db.json
│   └── .env.example
├── aws-lambda/               # Retired AWS backend (reference only)
├── data/db.json              # Product seed source of truth
├── public/                   # favicon, logos, images, fonts, sitemap
├── docs/                     # Walkthrough, plan, styling, LLM guide
├── .agile-v/                 # Requirements / decisions (team process)
├── .env.example              # Frontend env template
├── SECURITY.md               # Private vulnerability reporting
└── README.md                 # You are here

• Node.js 20+ (22 recommended)
• PostgreSQL 14+ running locally (or Docker)
• Optional: Stripe / Google / Brevo / Cloudinary / Shippo / Sentry accounts for full feature parity

You can explore much of the UI with minimal env (see below). Payments, OAuth, email, and AI need their respective keys.

Templates live in:

• Root: .env.example → copy to .env or .env.local (frontend)
• Backend: backend/.env.example → copy to backend/.env

Never commit real .env files (they are gitignored).

Vite already binds frontend :3000. Put the API on :4000:

# backend/.env
PORT=4000
CORS_ORIGINS=http://localhost:3000
FRONTEND_URL=http://localhost:3000
GOOGLE_CALLBACK_URL=http://localhost:4000/auth/google/callback

# root .env / .env.local
VITE_LAMBDA_API_URL=http://localhost:4000

The name VITE_LAMBDA_API_URL is historical (AWS Lambda era). It now points at the Express API. Do not point production at the old API Gateway URL — that stack is being retired.

1. Postgres — install locally or docker run Postgres; create DB/user; paste into DATABASE_URL.
2. JWT_SECRET — openssl rand -base64 64 (never put this in the frontend).
3. Stripe — Dashboard → Developers → API keys; use test keys locally. Webhooks: Stripe CLI stripe listen --forward-to localhost:4000/payment/webhook.
4. Google OAuth — Google Cloud Console → OAuth client → Authorized redirect URI must exactly match GOOGLE_CALLBACK_URL.
5. Brevo / Shippo / Cloudinary / Sentry — create free/test accounts; copy keys into backend/.env (and frontend where noted).
6. LLM keys — see docs/LLM_MODEL_SELECTION.md; any non-empty subset enables AI insights.

# Clone
git clone https://github.com/arnobt78/Ecommerce-Shop-1-BookStore--React-FullStack.git
cd Ecommerce-Shop-1-BookStore--React-FullStack

# --- Backend ---
cd backend
cp .env.example .env
# edit .env: DATABASE_URL, JWT_SECRET, PORT=4000, CORS_ORIGINS=http://localhost:3000
npm install
npm run prisma:generate
npm run prisma:push
npm run seed
npm run dev
# → http://localhost:4000  |  health: GET /api/health

# --- Frontend (new terminal, repo root) ---
cd ..
cp .env.example .env.local
# set VITE_LAMBDA_API_URL=http://localhost:4000
npm install
npm run dev
# → http://localhost:3000

One-click launch badge (same as the header):

More info: https://diploi.com/

Seeded by npm run seed (User.isDemo = true). The Login page loads them from GET /auth/demo-accounts — no passwords in the frontend bundle.

Prefer the Login page demo dropdown (one-click POST /auth/demo-login) while learning.

Guards live in src/routes/ProtectedRoute.tsx (requiredRole="admin" for admin trees). Admin pages are lazy-loaded so customers never download the admin chunk on first paint.

Base URL = VITE_LAMBDA_API_URL (e.g. http://localhost:4000). Auth: Authorization: Bearer <jwt> unless noted.

All services import one base URL:

// src/lib/apiBase.ts
export const API_BASE_URL =
  import.meta.env.VITE_LAMBDA_API_URL || "http://localhost:3000";

Example pattern (simplified):

const res = await fetch(`${API_BASE_URL}/products`, {
  headers: { Authorization: `Bearer ${token}` },
});
if (!res.ok) throw await throwApiError(res);
return res.json();

Hooks wrap services. After a mutation succeeds, helpers in src/utils/queryInvalidation.ts invalidate every related key (lists, detail, admin stats, badges) so the UI updates without reload.

Rule of thumb: if you add a new write API, add/extend an invalidation helper — never leave stale screens.

JWT + role + user id live in sessionStorage. ProtectedRoute checks them. Logout calls queryClient.clear() so persisted Query cache cannot leak across accounts.

Route (Zod + auth middleware) → Service (Prisma / Stripe / email) → JSON response

Ownership for customer resources comes from req.user.id (JWT), never from a client-supplied user id — important for addresses and tickets.

Products are eBook downloads (Dashboard library). Physical warehouse fields were intentionally not added. Shippo/address book support admin demos and optional shipping metadata, not a warehouse WMS.

How to reuse in another project

1. Copy the primitive + its Tailwind classes (or extract a design-token layer).
2. Keep props narrow and typed — match existing call sites.
3. Prefer composition over forks (PageHeader + DataTable instead of one mega-page).

Pairing convention:

productService.ts  ↔  useProducts.ts
ticketService.ts   ↔  useTickets.ts
adminService.ts    ↔  useAdmin.ts

When adding a domain elsewhere: service (HTTP) → hook (Query) → page (UI) — same three layers.

Page width comes from one wrapper in App.tsx:

mx-auto max-w-9xl px-2 sm:px-4 xl:px-8

Do not nest another max-w-* on pages or you will desync Header/Footer.

Frontend: React 19, Vite, TypeScript, React Router 7, TanStack Query, TanStack Table, Tailwind CSS, Lucide, Framer Motion, Sonner, SPA, JWT sessionStorage, Google OAuth callback, code splitting, localStorage cart, persisted query cache

Backend: Express, Prisma, PostgreSQL, Zod, Helmet, express-rate-limit, bcrypt, jsonwebtoken, pdfkit, Stripe webhooks, Brevo, Shippo, Cloudinary, Sentry tunnel, multi-provider LLM insights

E-commerce: eBook storefront, shopping cart, checkout, order timeline, address book, reviews, support tickets, admin analytics, inventory stock, refunds, shipping labels, RBAC

Learning: full-stack project, educational codebase, reusable UI primitives, API design, cache invalidation, environment configuration

Please read SECURITY.md before reporting issues.

• Private reports only: contact@arnobmahmud.com
• Do not file public GitHub issues for vulnerabilities
• Do not attach real secrets or .env files

This is an educational open-source project. Contributions are welcome:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Match existing patterns (TypeScript strict, shared UI, Query invalidation)
4. Run npm run lint and npm run typecheck (and the same under backend/)
5. Open a Pull Request with a clear description

• Functional React components + hooks
• No any — prefer precise types
• Reuse components/ui instead of one-off markup
• Invalidate all affected Query keys after writes
• Never commit secrets

CodeBook is both a working eBook store and a teaching codebase: Vite SPA frontend, Express/Prisma API, real Stripe/auth/admin flows, and careful cache/invalidation habits. Use the legacy live demo to explore the UX today; use the local Vite + backend/ stack to learn the post-AWS architecture as Coolify/Vercel cutover continues.

If you build something on top of it, share it — and enjoy the process.

This project is licensed under the MIT License. Feel free to use, modify, and distribute the code as per the terms of the license.

This is an open-source project — feel free to use, enhance, and extend this project further!

If you have any questions or want to share your work, reach out via GitHub or my portfolio at https://www.arnobmahmud.com.