Fullstack E-Commerce Project

A modern, production-ready e-commerce platform built with Next.js, TypeScript, Express, and MongoDB. Features professional cart management, user authentication, product catalogs, and order processing, including a comprehensive admin dashboard with analytics and audit logging.

Features

Core Functionality

• User Authentication: JWT-based registration and login with role-based permissions

• Product Management: CRUD operations for products with categories and inventory tracking

• Shopping Cart: Professional cart system with server-side calculations and guest support

• Order Management: Complete order lifecycle management with status tracking

• Payment Integration: Multiple payment gateways (Bkash, Nagad, Stripe) with demo processing

• Admin Dashboard: Comprehensive admin interface for managing products, orders, categories, users, analytics, and audit logs

• Search & Wishlist: Advanced search with autocomplete and personal wishlist management

Cart System Highlights

• Server-side price and stock validation

• Guest user support with cart persistence

• Cart merge functionality on user login

• Professional business logic calculations:

  • Subtotal = (price × quantity)
  • Tax = (subtotal - discount) × tax_rate
  • Shipping = rule-based (free over $50, otherwise $5.99)
  • Total = subtotal - discount + tax + shipping

Technical Features

• TypeScript throughout for type safety

• Responsive design with Tailwind CSS

• RESTful API architecture

• MongoDB with Mongoose ODM

• Input validation and error handling

• Environment-based configuration

• Role-based access control with permissions

• Audit logging for admin actions

• Advanced search with filtering and pagination

Tech Stack

Frontend

• Next.js 16 - React framework with App Router

• TypeScript - Type-safe JavaScript

• Tailwind CSS - Utility-first CSS framework

• Custom Hooks - State management for cart and auth

• Admin components for dashboard management

• Advanced UI components with shadcn/ui

Backend

• Node.js - JavaScript runtime
• Express.js - Web framework
• TypeScript - Type-safe server code
• MongoDB - NoSQL database
• Mongoose - MongoDB object modeling
• JWT - Authentication tokens
• bcryptjs - Password hashing
• Role-based permissions with middleware
• Winston - Structured logging
• csrf-csrf - CSRF protection
• express-mongo-sanitize - NoSQL injection prevention
• xss-clean - XSS prevention
• helmet - Security headers
• ioredis - Redis client for rate limiting

Project Structure

See PROJECTSTRUCTURE.md for detailed directory structure and architecture overview.

Getting Started

Prerequisites

• Node.js 18+
• MongoDB (local or cloud instance)
• npm or yarn

Installation

1. Clone the repository

    git clone git@github.com:joinvnexus/fullstack-ecommerce.git
   cd fullstack-ecommerce

2. Setup Backend

   cd backend
   npm install
   cp .env.example .env
   # Edit .env with your MongoDB connection and JWT secrets
   npm run build
   npm run start

3. Setup Frontend (in a new terminal)

   cd frontend
   npm install
   npm run dev

Environment Configuration

Create .env files in both backend/ and frontend/ directories. See .env.example in each directory for all available variables.

Backend (.env)

# Server
PORT=5000
NODE_ENV=development

# Database
MONGODB_URI=mongodb+srv://user:pass@host/db?retryWrites=true&w=majority

# Authentication
JWT_SECRET=your_jwt_secret_here
JWT_REFRESH_SECRET=your_jwt_refresh_secret_here
JWT_EXPIRE=7d

# Frontend
FRONTEND_URL=http://localhost:3000
APP_URL=http://localhost:5000

# Redis Cache
REDIS_URL=redis://localhost:6379

# CSRF Protection (required in production)
CSRF_SECRET=your_csrf_secret_here

# Stripe
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Email
SMTP_HOST=smtp.gmail.com
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password

# Payment Gateways (optional)
BKASH_APP_KEY=...
NAGAD_MERCHANT_ID=...

Frontend (.env.local)

NEXT_PUBLIC_API_URL=http://localhost:5000/api
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...

Security: Never commit .env files. Always use .env.example to document required variables.

API Endpoints

Authentication

• POST /api/auth/register - User registration
• POST /api/auth/login - User login
• GET /api/auth/me - Get current user (requires auth)

Products

• GET /api/products - List products
• GET /api/products/:id - Get product details
• POST /api/products - Create product (admin)
• PUT /api/products/:id - Update product (admin)
• DELETE /api/products/:id - Delete product (admin)

Categories

• GET /api/categories - List categories
• POST /api/categories - Create category (admin)
• PUT /api/categories/:id - Update category (admin)
• DELETE /api/categories/:id - Delete category (admin)

Cart (Guest & Authenticated)

• GET /api/cart - Get current cart
• POST /api/cart/items - Add item to cart
• PUT /api/cart/items/:itemId - Update item quantity
• DELETE /api/cart/items/:itemId - Remove item from cart
• DELETE /api/cart - Clear cart
• POST /api/cart/merge - Merge guest cart on login

Orders

• GET /api/orders - List user orders
• GET /api/orders/:id - Get order details
• POST /api/orders - Create order
• PUT /api/orders/:id - Update order status (admin)

Search

• GET /api/search - Search products with filters

Wishlist

• GET /api/wishlist - Get user wishlist
• POST /api/wishlist - Add to wishlist
• DELETE /api/wishlist/:id - Remove from wishlist

Admin

• GET /api/admin/dashboard/stats - Get dashboard statistics
• GET /api/admin/products - List all products (admin)
• GET /api/admin/orders - List all orders (admin)
• GET /api/admin/users - List all users (admin)
• GET /api/admin/categories - List all categories (admin)
• GET /api/admin/audit - Get audit logs
• PUT /api/admin/orders/:id/status - Update order status (admin)
• DELETE /api/admin/products/:id - Delete product (admin)

Development

Available Scripts

Backend

• npm run dev - Development server with hot reload
• npm run build - Build for production
• npm run start - Start production server
• npm run seed - Seed database with sample data

Frontend

• npm run dev - Development server
• npm run build - Build for production
• npm run start - Start production server
• npm run lint - Run ESLint

Database Seeding

To populate the database with sample data:

cd backend
npm run seed

Security Features

Authentication & Authorization

• Password hashing with bcryptjs (10 rounds)
• JWT access tokens (short-lived) and refresh tokens (30-day rotation)
• Secure httpOnly cookies for token storage (XSS resistant)
• Role-based access control (RBAC) with middleware
• Password complexity policy: minimum 8 characters with uppercase, lowercase, number, and special character

CSRF Protection

• Double Submit Cookie Pattern via csrf-csrf
• Tokens issued through /api/csrf-token endpoint
• Automatic token refresh on 403 responses
• Webhook endpoints excluded from CSRF (server-to-server)

Data Security

• Input sanitization with express-mongo-sanitize (NoSQL injection prevention)
• XSS protection with xss-clean
• Security headers via helmet()
• CORS restricted to configured FRONTEND_URL
• Raw body parsing for Stripe webhook signature verification

Rate Limiting

• Redis-backed rate limiting via rate-limit-redis
• Configurable limits per endpoint type:
  • Login: 5 attempts / 15 minutes (production)
  • Registration: 5 attempts / hour
  • Password change: 5 attempts / hour
  • Password reset: 5 attempts / hour
• IP blocking after repeated violations (30-minute TTL)

Additional Protections

• Audit logging for admin actions
• Debug endpoints restricted to development mode
• Input validation with Zod schemas
• Structured logging with Winston (sensitive data filtered)

UI/UX

• Responsive design for all devices
• Modern, clean interface
• Loading states and error handling
• Accessible components
• SEO optimized with Next.js

Business Logic

Cart Calculations

The cart system implements professional e-commerce business logic:

1. Price Preservation: Product prices are saved at time of order (price snapshot)
2. Server Validation: All calculations happen server-side, never trusting frontend data
3. Stock Management: Stock validation on all operations, reduction only on order completion
4. Tax & Shipping: Configurable tax rates and rule-based shipping costs
5. Guest Support: Full cart functionality for unauthenticated users

Order Processing

• Atomic order creation with stock reduction
• Payment processing integration points
• Order status tracking
• Inventory management

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support, email projoy.naidu.dev@gmail.com or create an issue in the repository.

---

Built with ❤️ using Next.js, Express, and MongoDB