🛒 E-Commerce Platform

A full-stack e-commerce application built with React, Node.js, Express, and MongoDB. This repository is a monorepo containing both the frontend storefront and the backend API.

---

📌 Purpose

This README is written so that a developer who did not build the project can understand the system and run it step by step.

---

📸 What the System Does

• Customer storefront with product browsing, filtering, cart, and checkout.
• Authentication with secure login/register, JWT access and refresh tokens.
• User profile editing and order history.
• Admin dashboard for managing products, orders, and users.
• Light/dark theme toggle.
• Security middleware protecting the backend API.

---

🧠 Architecture Overview

The system is split into two main parts:

1. Backend (backend/)

   • Express API server.
   • MongoDB database connection.
   • Endpoints for auth, products, cart, orders, and admin actions.
   • Security middleware for CORS, rate limiting, headers, and input sanitization.

2. Frontend (frontend/)

   • React application using Vite.
   • Redux Toolkit for global state.
   • Axios for communicating with the backend.
   • Pages for customers and admin users.

---

🗂 Folder Structure

The repository is organized as a monorepo with separate frontend and backend applications.

Backend

backend/
├── server.js                  # Application entry point
├── src/
│   ├── app.js                 # Express app and middleware configuration
│   ├── config/
│   │   └── database.js        # MongoDB connection setup
│   ├── routes/                # API route definitions
│   ├── controllers/           # Business logic and request handlers
│   ├── models/                # Mongoose schemas and models
│   ├── middleware/            # Authentication, validation, security, and error handling
   │   └── ...
│   ├── services/              # Reusable service and domain logic
│   └── utils/                 # Shared helper utilities

Frontend

frontend/
├── index.html                 # HTML template for Vite
├── src/
│   ├── main.jsx               # React app bootstrap
│   ├── App.jsx                # Root component, routes, and auth hydration
│   ├── store/                 # Redux store and slices
│   ├── hooks/                 # Custom hooks used across the app
│   ├── components/            # Reusable UI components
│   ├── pages/                 # Page-level views and routing targets
│   └── styles/                # Global styles and theme variables

---

🔧 How the Backend Works

1. backend/server.js loads environment variables and starts the Express app.
2. backend/src/config/database.js connects to MongoDB using MONGODB_URI.
3. backend/src/app.js configures middleware:
   • CORS with origin validation and cookies.
   • Compression and JSON parsing.
   • Cookie parsing.
   • Rate limiting.
   • Security protections (Helmet, XSS, HPP, Mongo sanitization).
4. API routes are mounted under /api/v1/.
5. Protected routes verify JWT tokens using auth middleware.
6. Errors are handled globally.

Backend Environment Variables

Create a .env file in backend/ with at least:

PORT=5000
MONGODB_URI=mongodb://localhost:27017/ecommerce-db
JWT_ACCESS_SECRET=yourAccessSecret
JWT_REFRESH_SECRET=yourRefreshSecret
JWT_ACCESS_EXPIRES=15m
JWT_REFRESH_EXPIRES=7d
CORS_ORIGIN=http://localhost:5173
FRONTEND_URL=http://localhost:5173
NODE_ENV=development

---

🔧 How the Frontend Works

1. The React app loads in the browser.
2. Routes render the requested page.
3. Auth state is restored from backend cookies.
4. User actions call backend APIs for auth, products, cart, and orders.
5. Protected routes block access for unauthenticated or unauthorized users.
6. Redux stores user, cart, and UI state.

---

🚀 Running the App Locally

1. Install dependencies

cd backend
npm install
cd ../frontend
npm install

2. Start backend

From the repo root:

npm run dev:backend

Or from backend/:

npm run dev

3. Start frontend

From the repo root:

npm run dev:frontend

Or from frontend/:

cd frontend
npm run dev

4. Open the application

• Frontend: http://localhost:5173
• Backend API base URL: http://localhost:5000/api/v1
• Health check: http://localhost:5000/health

---

📡 Major API Endpoints

Authentication

• POST /api/v1/auth/register — Register a new user.
• POST /api/v1/auth/login — Login and receive auth cookies.
• GET /api/v1/auth/me — Get current user.
• PATCH /api/v1/auth/profile — Update profile.
• POST /api/v1/auth/logout — Logout and clear cookies.
• POST /api/v1/auth/refresh — Refresh the access token.

Products

• GET /api/v1/products — List products.
• GET /api/v1/products/:id — Get one product.
• POST /api/v1/products — Create product (admin only).
• PUT /api/v1/products/:id — Update product (admin only).
• DELETE /api/v1/products/:id — Delete product (admin only).

Cart

• GET /api/v1/cart — Get current cart.
• POST /api/v1/cart/items — Add item.
• PUT /api/v1/cart/items/:itemId — Update quantity.
• DELETE /api/v1/cart/items/:itemId — Remove item.

Orders

• POST /api/v1/orders — Create order.
• GET /api/v1/orders — Get user's orders.
• GET /api/v1/orders/all — Get all orders (admin only).
• GET /api/v1/orders/:id — Get order details.
• PATCH /api/v1/orders/:id/status — Update order status (admin only).

Admin

• GET /api/v1/admin/dashboard — Admin statistics.
• GET /api/v1/admin/users — List users.
• PATCH /api/v1/admin/users/:userId — Update user role/status.
• DELETE /api/v1/admin/users/:userId — Delete a user.

---

⚙️ Available Scripts

Root

• npm run dev:backend — Start backend dev server.
• npm run dev:frontend — Start frontend dev server.
• npm run build:frontend — Build frontend.
• npm run build:backend — Start backend in production mode.
• npm run test:backend — Run backend tests.

Backend

• npm run dev — Start backend with nodemon.
• npm start — Start backend with node.
• npm test — Run Jest tests.

Frontend

• npm run dev — Start Vite.
• npm run build — Build production app.
• npm run preview — Preview built app.

---

🔒 Security Summary

• JWT access and refresh tokens stored in HTTP-only cookies.
• CORS origin whitelist.
• Rate limiting for API requests.
• Helmet secure headers.
• XSS cleaning, HPP protection, and MongoDB input sanitization.

---

✅ For a New Developer

1. Install dependencies in backend/ and frontend/.
2. Create backend/.env with the required variables.
3. Start backend and frontend.
4. Visit http://localhost:5173.
5. Register, login, and explore the storefront and admin pages.

---

❤️ Built With

React, Vite, Redux Toolkit, Node.js, Express, MongoDB, JWT, Helmet.