Features
Relevant source files
The following files were used as context for generating this wiki page:This document provides a comprehensive overview of the key features implemented in the Laptop E-commerce Web App. The application is a full-stack solution built with React on the frontend and NestJS on the backend, offering a complete online shopping experience for laptops.
The features cover the entire user journey, from authentication and product discovery to checkout and post-purchase activities like leaving reviews. It also includes a dedicated admin dashboard for managing the platform's core entities.
Core Feature Summary
The application provides a standard set of e-commerce functionalities.
| Feature | Description |
|---|---|
| Authentication & Authorization | JWT-based authentication with access/refresh tokens and role-based access control (User/Admin). |
| Products & Categories | Full CRUD for admins, with public-facing product listings, details, search, and filtering. |
| Shopping Cart | Persistent cart for logged-in users, allowing items to be added, updated, and removed. |
| Orders & Discounts | Order creation from the cart, history viewing, and a rank-based discount system. |
| Payments | Integration with SePay for QR code payments and support for Cash on Delivery (COD). |
| Product Reviews | Users can leave 1-5 star reviews with comments on products they have purchased. |
| Admin Dashboard | A dedicated interface for managing users, products, and orders, with summary and detailed statistics. |
| Transactional Emails | Automated welcome emails are sent to new users upon successful registration. |
Sources: README.md:14-23
Authentication & Authorization
The system uses JSON Web Tokens (JWT) for securing API endpoints and managing user sessions. It supports two user roles: User and ADMIN, with specific routes and functionalities protected by role-based guards.
Sources: README.md:15, frontend/src/App.tsx:16-18, 79-118
Authentication Flow
The login process involves exchanging user credentials for a pair of JWTs: an access token and a refresh token. The access token is short-lived and used to authenticate subsequent API requests, while the long-lived refresh token is used to obtain a new access token without requiring the user to log in again.
The diagram below illustrates the login and token refresh sequence.
Sources: README.md:73-75
Frontend Routing and Protection
The frontend application uses react-router-dom to define public, protected, and admin-only routes. The <ProtectedRoute> component wraps sensitive pages, checking for user authentication and, optionally, a required role (UserRole.ADMIN).
The following diagram shows the high-level routing structure.
Sources: frontend/src/App.tsx:39-118
Products & Categories
This feature is central to the e-commerce platform, allowing users to browse, search, and view products. Administrators have full CRUD (Create, Read, Update, Delete) capabilities over both products and categories through the admin dashboard.
Sources: README.md:16, frontend/src/pages/admin/AdminCategoriesPage.tsx
Product Listing and Filtering
The main products page (/products) allows users to view a paginated list of all available laptops. Users can filter the list by category and sort the results by creation date, name, or price in ascending or descending order. A search bar is also available for finding products by name.
The state management for products, categories, and filtering is handled by the useProductStore (Zustand).
The flow for fetching and filtering products on the frontend is as follows:
Cart, Orders, and Stock Management
Shopping Cart
Authenticated users have a persistent shopping cart. They can add, update quantities, or remove products from their cart. The cart's state is managed via API calls to the /api/cart endpoints.
Sources: README.md:17, 77-80
Order Creation and Discounts
Users can create an order from the items in their cart. The system supports a rank-based discount structure, which is applied at the time of order creation.
| User Rank | Discount |
|---|---|
| Bronze | 0% |
| Silver | 5% |
| Gold | 10% |
| Diamond | 20% |
Sources: README.md:18
Stock Reservation System
To prevent overselling and handle abandoned carts, the application implements a stock reservation system instead of immediately decrementing stock on order creation.
Logic:
- Order Creation: When a
PENDINGorder is created, the quantity of each item is moved fromstockQuantityto areservedQuantityfield for the corresponding product. The available stock is calculated asstockQuantity - reservedQuantity. - Payment Success: When payment is confirmed (
PAID),stockQuantityis decremented by the ordered amount, andreservedQuantityis also decremented, effectively consuming the reserved stock. - Order Cancellation/Failure/Timeout: If an order is cancelled, payment fails, or it expires (after 30 minutes), the
reservedQuantityis restored back to zero, making the stock available again.
This flow is detailed in the testing guide.
Sources: TESTING_GUIDE.md:5-40
Payments
The application supports two primary payment methods:
- SePay QR Code: Generates a unique QR code for the order amount. The backend listens for a webhook from SePay to confirm payment.
- Cash on Delivery (COD): Allows users to pay upon delivery.
Sources: README.md:19
SePay QR Payment Flow
The SePay integration involves generating a QR code and handling an asynchronous webhook to confirm the transaction.
Sources: README.md:19, 85-88, 100-103
Product Reviews
Users who have purchased a product are able to leave a review, consisting of a 1-5 star rating and an optional text comment. The average rating is calculated and displayed on the product detail page.
Sources: README.md:20
Review Data Structure
The frontend defines a clear structure for review data, which is consistent with the backend API response.
// Source: frontend/src/types/interfaces/reviews.ts:9-15
export interface Review {
id: string;
rating: number;
comment: string;
createdAt: Date;
updatedAt: Date;
}
Sources: frontend/src/types/interfaces/reviews.ts:9-15
Admin Dashboard
A comprehensive admin dashboard is available for users with the ADMIN role. It is a separate section of the frontend application, protected by the ProtectedRoute component.
The dashboard provides management interfaces for:
- Users
- Products (CRUD)
- Categories (CRUD)
- Orders (View details, update status)
- Dashboard with summary and detailed statistics.
Sources: README.md:21, 89-94, frontend/src/App.tsx:106-118, frontend/src/pages/admin/AdminCategoriesPage.tsx