/HaoNgo232/laptop-e-commerce-web-app

Wiki directory

Browse AI-generated documentation for any repository.

Overview

Relevant source files

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

The Laptop Shop is a full-stack e-commerce web application designed for selling laptops. It features a modern architecture with a React-based Single Page Application (SPA) for the frontend and a modular NestJS application for the backend. The system supports a complete e-commerce workflow, including user authentication, product catalog management, a persistent shopping cart, an order processing system with rank-based discounts, and payment integration with SePay QR codes.

The project is containerized using Docker, allowing for a streamlined setup and consistent development and production environments. It exposes a RESTful API for communication between the frontend and backend, with features like JWT-based security, DTO validation, and role-based access control for a dedicated admin dashboard.

Sources: README.md:3-10

Architecture

The application follows a classic client-server model, with a clear separation between the frontend and backend. It is designed as a monolith but with a modular backend structure that facilitates future scaling.

Sources: README.md:27-29

Generating architecture diagram...

This diagram shows the high-level architecture, where the React frontend communicates with the NestJS backend via a REST API, and the backend interacts with the PostgreSQL database using TypeORM.

Sources: README.md:27-29

Frontend

The frontend is a React Single Page Application built with Vite. It uses a modern toolchain for a fast and responsive user experience.

UI Framework: React 19 with TypeScript.
Styling: TailwindCSS 4 and shadcn/ui for a component-based design system.
State Management: Zustand is used for global state management.
Data Fetching: TanStack Query (React Query) handles server state, caching, and data synchronization.
Routing: React Router manages client-side navigation.

Sources: README.md:32-33, frontend/package.json:15-32

Backend

The backend is built on the NestJS framework, providing a scalable and modular Node.js server-side application.

Framework: NestJS 11 with TypeScript.
Database: PostgreSQL is the primary database.
ORM: TypeORM is used for database interaction and entity management.
Authentication: JWT (JSON Web Tokens) are used for securing API endpoints, with separate access and refresh tokens.
API: A RESTful API is exposed with Swagger documentation available.
Other: Includes modules for mailing (via @nestjs-modules/mailer with EJS templates) and scheduled tasks.

Sources: README.md:31, backend/package.json:43-61, backend/README.md:3-5

Tech Stack

The following table summarizes the key technologies used in the project.

Sources: README.md:30-35, frontend/package.json, backend/package.json

Project Structure

The repository is organized into two main directories, frontend and backend, reflecting the separation of concerns.

Web-Ecom/
  backend/        # NestJS API (auth, products, cart, orders, etc.)
  frontend/       # React SPA (components, hooks, pages, services, etc.)
  docker-compose.yml

backend/: Contains the entire NestJS application, including modules for different domains like auth, products, orders, and the admin panel.
frontend/: Contains the React application, with a standard structure separating pages, components, hooks, services, and stores.

Sources: README.md:37-42

Core Features

The application provides a comprehensive set of features for an e-commerce platform.

Feature	Description -
Authentication	User registration and login system using JWT for access and refresh tokens. Role-based authorization (User/Admin). -
Products & Categories	Admins have full CRUD operations. Users can list, view details, search, filter by category, and use pagination. -
Cart	Persistent cart for logged-in users, allowing them to add, update, and remove items. -
Orders	Users can create orders from their cart, view order history, and cancel orders. A rank-based discount system (Bronze, Silver, Gold, Diamond) is applied. -
li>
Payments	Integration with SePay for QR code payments and a webhook for handling payment status updates. Cash on Delivery (COD) is also supported. -
Reviews	Customers can leave 1-5 star reviews with comments for products they have purchased. Average ratings are displayed on product pages. -
li>
Admin Dashboard	A dedicated admin section with summary metrics and management interfaces for users, products, and orders. -
Mail	Transactional emails, such as a welcome email upon registration, are sent using EJS templates. -

Sources: README.md:14-25

Frontend Application Structure

The frontend application uses react-router-dom to define public, protected, and admin-only routes. Access to protected routes is controlled by the ProtectedRoute component, which checks for user authentication and, optionally, a required role.

Sources: frontend/src/App.tsx:8-12

The diagram below illustrates the main routing structure of the application.

Generating architecture diagram...

This diagram shows how routes are organized into public, user-protected, and admin-protected sections.

Sources: frontend/src/App.tsx:40-141

API Interaction Example

The frontend communicates with the backend via a REST API. The following sequence diagram shows the flow for adding an item to the cart, which is a common authenticated action.

Generating architecture diagram...

This flow demonstrates the interaction between the client, server, and database for a core e-commerce feature, including the security check via JwtAuthGuard.

Sources: README.md:110-113, TESTING_GUIDE.md:65-72

Local Development & Deployment

The project is configured to run with Docker and Docker Compose, which simplifies the setup process.

Quick Start:
To run the entire stack (frontend, backend, database), use the following command from the project root:

docker compose up -d

This command starts three services with default ports:

Frontend: http://localhost
Backend API: http://localhost:3000
PostgreSQL: localhost:5432

An alternative local development setup involves running only the database in Docker and the frontend/backend services directly on the host machine for easier hot-reloading and debugging.

Sources: README.md:46-56, README.md:67-86

Overview

Relevant source files

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

Sources: README.md:3-10

Architecture

Sources: README.md:27-29

Generating architecture diagram...

This diagram shows the high-level architecture, where the React frontend communicates with the NestJS backend via a REST API, and the backend interacts with the PostgreSQL database using TypeORM.

Sources: README.md:27-29

Frontend

The frontend is a React Single Page Application built with Vite. It uses a modern toolchain for a fast and responsive user experience.

UI Framework: React 19 with TypeScript.
Styling: TailwindCSS 4 and shadcn/ui for a component-based design system.
State Management: Zustand is used for global state management.
Data Fetching: TanStack Query (React Query) handles server state, caching, and data synchronization.
Routing: React Router manages client-side navigation.

Sources: README.md:32-33, frontend/package.json:15-32

Backend

The backend is built on the NestJS framework, providing a scalable and modular Node.js server-side application.

Framework: NestJS 11 with TypeScript.
Database: PostgreSQL is the primary database.
ORM: TypeORM is used for database interaction and entity management.
Authentication: JWT (JSON Web Tokens) are used for securing API endpoints, with separate access and refresh tokens.
API: A RESTful API is exposed with Swagger documentation available.
Other: Includes modules for mailing (via @nestjs-modules/mailer with EJS templates) and scheduled tasks.

Sources: README.md:31, backend/package.json:43-61, backend/README.md:3-5

Tech Stack

The following table summarizes the key technologies used in the project.

Sources: README.md:30-35, frontend/package.json, backend/package.json

Project Structure

The repository is organized into two main directories, frontend and backend, reflecting the separation of concerns.

Web-Ecom/
  backend/        # NestJS API (auth, products, cart, orders, etc.)
  frontend/       # React SPA (components, hooks, pages, services, etc.)
  docker-compose.yml

backend/: Contains the entire NestJS application, including modules for different domains like auth, products, orders, and the admin panel.
frontend/: Contains the React application, with a standard structure separating pages, components, hooks, services, and stores.

Sources: README.md:37-42

Core Features

The application provides a comprehensive set of features for an e-commerce platform.

Feature	Description -
Authentication	User registration and login system using JWT for access and refresh tokens. Role-based authorization (User/Admin). -
Products & Categories	Admins have full CRUD operations. Users can list, view details, search, filter by category, and use pagination. -
Cart	Persistent cart for logged-in users, allowing them to add, update, and remove items. -
Orders	Users can create orders from their cart, view order history, and cancel orders. A rank-based discount system (Bronze, Silver, Gold, Diamond) is applied. -
li>
Payments	Integration with SePay for QR code payments and a webhook for handling payment status updates. Cash on Delivery (COD) is also supported. -
Reviews	Customers can leave 1-5 star reviews with comments for products they have purchased. Average ratings are displayed on product pages. -
li>
Admin Dashboard	A dedicated admin section with summary metrics and management interfaces for users, products, and orders. -
Mail	Transactional emails, such as a welcome email upon registration, are sent using EJS templates. -

Sources: README.md:14-25

Frontend Application Structure

Sources: frontend/src/App.tsx:8-12

The diagram below illustrates the main routing structure of the application.

Generating architecture diagram...

This diagram shows how routes are organized into public, user-protected, and admin-protected sections.

Sources: frontend/src/App.tsx:40-141

API Interaction Example

The frontend communicates with the backend via a REST API. The following sequence diagram shows the flow for adding an item to the cart, which is a common authenticated action.

Generating architecture diagram...

This flow demonstrates the interaction between the client, server, and database for a core e-commerce feature, including the security check via JwtAuthGuard.

Sources: README.md:110-113, TESTING_GUIDE.md:65-72

Local Development & Deployment

The project is configured to run with Docker and Docker Compose, which simplifies the setup process.

Quick Start:
To run the entire stack (frontend, backend, database), use the following command from the project root:

docker compose up -d

This command starts three services with default ports:

Frontend: http://localhost
Backend API: http://localhost:3000
PostgreSQL: localhost:5432

An alternative local development setup involves running only the database in Docker and the frontend/backend services directly on the host machine for easier hot-reloading and debugging.

Sources: README.md:46-56, README.md:67-86