Getting Started

Relevant source files

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

• README.md
• backend/README.md
• frontend/README.md
• backend/package.json
• frontend/package.json
• frontend/src/App.tsx
• frontend/index.html
• TESTING_GUIDE.md

This guide provides instructions for setting up and running the Laptop E-commerce Web App project. The application is a full-stack e-commerce platform for selling laptops, featuring a React frontend and a NestJS backend. Key features include JWT authentication, product management, a shopping cart, order processing with rank-based discounts, and an admin dashboard.

The project is structured as a monorepo with two main directories: frontend for the React single-page application and backend for the NestJS RESTful API. The backend uses TypeORM with a PostgreSQL database. This guide covers setup using both Docker for a quick start and a hybrid local development approach.

Sources: README.md:3-10, README.md:21-24

Architecture & Tech Stack

The application follows a classic client-server architecture. The frontend is a React SPA that communicates with a modular NestJS backend via a RESTful API.

Sources: README.md:21-24

High-Level Architecture

The following diagram illustrates the high-level interaction between the system components.

Technology Stack

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

Layer	Technology
Backend	NestJS 11, TypeScript, TypeORM, PostgreSQL, JWT, Bcrypt, EJS
Frontend	React 19, TypeScript, Vite 6, TailwindCSS 4, shadcn/ui, Zustand 5, TanStack Query 5
Infra	Docker & Docker Compose

Sources: README.md:26-30, backend/package.json:40-60, frontend/package.json:13-31

Project Structure

The repository is organized into two primary sub-projects.

Web-Ecom/
  ├── backend/        # NestJS API
  ├── frontend/       # React SPA
  └── docker-compose.yml

• backend/: Contains the NestJS application source code, handling all business logic, API endpoints, and database interactions.
• frontend/: Contains the React application source code, responsible for the user interface and user experience.

Sources: README.md:32-37

Setup and Installation

There are two primary methods for setting up the development environment. The Docker-based approach is recommended for a quick start.

1. Quick Start (Docker)

This method runs the entire stack (frontend, backend, database) in Docker containers.

Prerequisites:

• Docker
• Docker Compose

Steps:

1. Navigate to the project root directory.
2. Run the following command:

   docker compose up -d
   

This command builds and starts all services defined in docker-compose.yml.

The diagram below shows the services launched by Docker Compose.

Default Service URLs:

• Frontend: http://localhost
• Backend API: http://localhost:3000
• Swagger Docs: http://localhost:3000/api/docs
• PostgreSQL: localhost:5432

Sources: README.md:38-50

2. Local Development (Hybrid)

This method involves running the PostgreSQL database in Docker while running the frontend and backend applications directly on your local machine. This is useful for active development with hot-reloading.

The setup flow is as follows:

Step 1: Start the Database

# From the project root
docker compose up -d postgres

This command starts only the PostgreSQL service.

Step 2: Run the Backend (NestJS)

# Navigate to the backend directory
cd backend

# Install dependencies
pnpm install

# Create a .env.development file (see Environment Variables section)

# Start the development server
pnpm dev

The backend will be available at http://localhost:3000. After starting, you can seed the database with sample data:

pnpm seed

Step 3: Run the Frontend (React)

# Navigate to the frontend directory
cd frontend

# Install dependencies
pnpm install

# Create a .env file with VITE_API_URL=http://localhost:3000

# Start the Vite development server
pnpm dev

The frontend will typically be available at http://localhost:5173.

Sources: README.md:58-86, backend/package.json:15, frontend/package.json:7

Environment Variables

Configuration is managed through environment variables. You must create the appropriate .env files in the backend and frontend directories.

Backend (backend/.env.development)

Variable	Description	Default/Example
NODE_ENV	Application environment	development
PORT	Port for the backend server	3000
DATABASE_HOST	Database host	localhost
DATABASE_PORT	Database port	5432
DATABASE_USERNAME	PostgreSQL username	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 time	1h
JWT_REFRESH_EXPIRATION_TIME	Refresh token expiration time	7d
MAIL_HOST	SMTP server host for sending emails	smtp.gmail.com
SMTP_USERNAME	SMTP username	your-email@gmail.com
SMTP_PASSWORD	SMTP password or app-specific password	your-app-password

Sources: README.md:88-110

Frontend (frontend/.env)

Variable	Description	Example
VITE_API_URL	The base URL of the backend API.	http://localhost:3000

Sources: README.md:112-114

Available Scripts

The package.json files in both the frontend and backend directories define several scripts for development, testing, and building.

Backend Scripts

Script	Description
pnpm dev	Starts the NestJS server in watch mode.
pnpm build	Compiles the TypeScript source code to JavaScript.
pnpm start	Starts the production-ready server from dist.
pnpm seed	Populates the database with sample data.
pnpm test	Runs Jest unit tests.

Sources: backend/package.json:12-29

Frontend Scripts

Script	Description
pnpm dev	Starts the Vite development server with HMR.
pnpm build	Builds the React app for production.
pnpm lint	Lints the source code using ESLint.
pnpm preview	Serves the production build locally for preview.

Sources: frontend/package.json:6-10

Demo Accounts

For testing and demonstration purposes, the database seeding script creates default user accounts with different roles.

Role	Email	Password
Admin	admin@gmail.com	admin123
Customer	customer@gmail.com	123456789

Sources: README.md:133-136