Documentation

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• backend/README.md
• TESTING_GUIDE.md
• frontend/README.md
• frontend/package.json
• backend/package.json
• frontend/src/App.tsx
• backend/src/products/controllers/admin-categories.controller.ts

This document provides a technical overview of the Laptop E-commerce Web App, a full-stack application for selling laptops. It covers the system architecture, technology stack, project structure, setup procedures, and a summary of the API. The application is built with a React frontend and a NestJS backend, interacting via a RESTful API.

Key features include JWT-based authentication, product and category management, a persistent shopping cart, an order system with rank-based discounts, SePay QR and COD payment methods, product reviews, and an admin dashboard for management tasks.

Sources: README.md:3-10

Architecture

The application follows a monolithic architecture with a clear separation between the frontend and backend, making it suitable for future scaling into microservices. The frontend is a React Single-Page Application (SPA), and the backend is a modular NestJS application. Communication occurs over a RESTful API via HTTP, with CORS enabled.

Sources: README.md:21-24

The diagram below illustrates the high-level system architecture.

Project Structure

The repository is organized into two main directories: frontend and backend, along with Docker configuration at the root.

Tech Stack

The project utilizes a modern technology stack for both frontend and backend development.

Component	Technology / Library	Version
Backend	NestJS	^11.0.1
	TypeScript	^5.7.3
	TypeORM	^0.3.24
	PostgreSQL (pg)	^8.16.0
	JWT (@nestjs/jwt)	^11.0.0
	Bcrypt	^6.0.0
	Mailer (@nestjs-modules/mailer)	^2.0.2
Frontend	React	^19.1.0
	Vite	^6.3.5
	TypeScript	~5.8.3
	TailwindCSS	^4.1.7
	shadcn/ui	N/A
	Zustand	^5.0.5
	TanStack Query	^5.77.0
	React Router	^7.6.0
Infra	Docker & Docker Compose	N/A

Sources: README.md:26-31, frontend/package.json:11-30, backend/package.json:30-47

Setup and Installation

There are two primary methods for setting up the development environment: using Docker for a quick start or running services locally.

Quick Start (Docker)

This is the recommended method for a fast setup. It requires Docker and Docker Compose to be installed.

1. Start all services:

   # From project root
   docker compose up -d
   

2. Access services:
   • Frontend: http://localhost
   • Backend API: http://localhost:3000
   • Swagger Docs: http://localhost:3000/api/docs

Sources: README.md:40-51

Local Development

This method involves running the database in Docker and the frontend/backend applications directly on the host machine.

1. Start the database:

   docker compose up -d postgres
   

2. Set up the Backend (NestJS):

   cd backend
   pnpm install
   # Create .env.development from the sample
   pnpm dev
   # Seed the database (optional)
   pnpm seed
   

3. Set up the Frontend (React):

   cd frontend
   pnpm install
   # Create .env with VITE_API_URL=http://localhost:3000
   pnpm dev
   

Sources: README.md:61-81, backend/README.md:20-26

Configuration

The application uses environment variables for configuration. These must be set up in .env files for local development.

Backend (backend/.env.development)

Variable	Description	Example
NODE_ENV	Application environment	development
PORT	Port for the backend server	3000
DATABASE_HOST	PostgreSQL host	localhost
DATABASE_PORT	PostgreSQL port	5432
DATABASE_USERNAME	PostgreSQL user	postgres
DATABASE_PASSWORD	PostgreSQL password	postgres
DATABASE_NAME	Database name	ecom_db
JWT_SECRET	Secret key for signing JWTs	replace-with-a-strong-secret
JWT_EXPIRATION_TIME	Access token expiration	1h
JWT_REFRESH_EXPIRATION_TIME	Refresh token expiration	7d
MAIL_HOST	SMTP server host	smtp.gmail.com
SMTP_USERNAME	SMTP username	your-email@gmail.com
SMTP_PASSWORD	SMTP password/app password	your-app-password
SEPAY_API_KEY	API key for SePay service
SEPAY_WEBHOOK_SECRET	Secret for verifying SePay webhooks

Sources: README.md:85-111

Frontend (frontend/.env)

Variable	Description	Example
VITE_API_URL	Base URL for the backend API	http://localhost:3000

Sources: README.md:113-115

API Overview

The backend exposes a RESTful API for the frontend to consume. The API is organized by resource and includes endpoints for authentication, products, cart, orders, payments, and admin functions. All admin endpoints are protected and require an ADMIN role.

Sources: README.md:117-118, backend/src/products/controllers/admin-categories.controller.ts:19-21

Key Endpoints

Method	Path	Description	Auth Required
POST	/api/auth/register	Register a new user.	No
POST	/api/auth/login	Log in and receive JWTs.	No
GET	/api/products	List all products with pagination.	No
GET	/api/products/:id	Get details for a single product.	No
GET	/api/cart	Get the current user's cart.	User
POST	/api/cart/items	Add an item to the cart.	User
POST	/api/orders	Create an order from the cart.	User
GET	/api/admin/dashboard/summary	Get summary metrics for the admin dashboard.	Admin
POST	/api/admin/categories	Create a new product category.	Admin
PUT	/api/admin/categories/:id	Update an existing category.	Admin
DELETE	/api/admin/categories/:id	Delete a category.	Admin

Sources: README.md:121-150, backend/src/products/controllers/admin-categories.controller.ts:24-49

Sequence Diagram: Create Order

The following diagram shows the sequence of events when a user creates an order.

Frontend Routing

The frontend application uses react-router-dom to manage navigation. It defines public routes, protected routes for authenticated users, and admin-only routes.

The main routing configuration is located in frontend/src/App.tsx.

Testing

The project includes a manual testing guide but does not currently have automated test suites implemented. The guide provides checklists and API testing examples for core functionalities like reserved stock management during the order process.

Manual Test Example: Reserved Stock

1. Create Order: A POST request to /api/orders with items.
2. Verify Stock: A GET request to /api/products/{id} should show that stockQuantity is unchanged, but reservedQuantity has increased.
3. Update Payment: A PATCH request to update the order's payment status to PAID.
4. Verify Final Stock: A GET request to /api/products/{id} should now show that stockQuantity has decreased and reservedQuantity is back to its previous value.

Sources: TESTING_GUIDE.md:5-32, README.md:162-163