Getting Started

Prerequisites

• Node.js 18+
• MongoDB Atlas account (or local MongoDB)
• Google Gemini API key (optional, for AI features)

Installation

cd Server
npm install

Environment Variables

Create a .env file in the Server directory:

PORT=5001
MONGODB_URI=mongodb+srv://<username>:<password>@cluster0.mongodb.net/nexcart
JWT_SECRET=your_jwt_secret_key
JWT_EXPIRES_IN=15m
JWT_REFRESH_EXPIRES_IN=7d
GEMINI_API_KEY=your_gemini_api_key

Run Development Server

npm run dev

Seed Database

Populates the database with demo users, categories, products, reviews, and orders:

npm run seed

Build & Start Production

npm run build
npm start

Demo Credentials (after seeding)

CI/CD Pipeline

The project uses GitHub Actions for continuous integration and Render for continuous deployment. Every push to main or master automatically runs the full pipeline.

Pipeline Overview

Push to main/master
        │
        ▼
┌─────────────────────┐
│   Lint & Build Job  │
│  ─────────────────  │
│  1. ESLint check    │
│  2. TypeScript check│
│  3. Build (tsc)     │
└────────┬────────────┘
         │ (passes)
         ▼
┌─────────────────────┐
│     Test Job        │
│  ─────────────────  │
│  133 tests via      │
│  Vitest + Supertest │
│  (in-memory MongoDB)│
└────────┬────────────┘
         │ (passes)
         ▼
┌─────────────────────┐
│  Render Auto-Deploy │
│  (main branch only) │
└─────────────────────┘

GitHub Actions Workflow

The workflow file is at .github/workflows/ci.yml. It runs two sequential jobs:

Job 1 — Lint & Build (lint-and-build):

1. Checks out code
2. Sets up Node.js 24
3. Installs dependencies (npm ci --ignore-scripts)
4. Runs ESLint (npm run lint)
5. Runs TypeScript type-check (npm run typecheck)
6. Compiles TypeScript (npm run build)

Job 2 — Test (test, runs after lint-and-build):

1. Checks out code
2. Sets up Node.js 24
3. Installs dependencies
4. Runs the full test suite (npm test) with CI-safe environment variables

The test job only runs if the lint-and-build job passes, preventing unnecessary test runs on broken code.

Testing Setup

Tests use Vitest for the test runner, Supertest for HTTP integration testing, and mongodb-memory-server to spin up a real in-memory MongoDB instance — no external database needed in CI.

src/
├── __tests__/setup.ts               # Global setup: starts MongoDB, sets env vars, wipes collections between tests
├── utils/__tests__/helpers.test.ts  # generateSlug — 11 tests
├── utils/__tests__/errors.test.ts   # Custom error classes — 18 tests
├── utils/__tests__/response.test.ts # sendSuccess / sendError — 9 tests
├── middlewares/__tests__/
│   ├── validate.test.ts             # Zod validation middleware — 17 tests
│   ├── role.test.ts                 # authorize() RBAC middleware — 5 tests
│   └── auth.test.ts                 # authenticate() JWT middleware — 7 integration tests
└── controllers/__tests__/
    ├── auth.test.ts                 # /api/auth routes — 16 tests
    ├── category.test.ts             # /api/categories routes — 12 tests
    ├── product.test.ts              # /api/products routes — 15 tests
    ├── cart.test.ts                 # /api/cart routes — 10 tests
    └── order.test.ts                # /api/orders routes — 13 tests
                                     Total: 133 tests

Running Tests Locally

# Run all tests once
npm test

# Run in watch mode (re-runs on file changes)
npm run test:watch

# Run with coverage report
npm run test:coverage

Coverage reports are generated in coverage/ (text output + lcov for CI tools).

All Scripts

Render Deployment

The backend is deployed on Render at the production URL. Render is connected to the main branch and auto-deploys whenever a push reaches main — which only happens after the full CI pipeline passes on GitHub Actions.

Deployment flow:

1. Developer pushes to master → CI runs
2. master is merged into main → Render detects the push
3. Render pulls the latest code, runs npm run build, then npm start
4. Zero-downtime deploy (Render keeps the old instance running until the new one is healthy)

API Response Format

All endpoints return a standardized response:

{
  "success": true,
  "message": "Description of the result",
  "data": {},
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 50,
    "totalPages": 5
  }
}

Error responses:

{
  "success": false,
  "message": "Error description",
  "errorDetails": "Technical details (dev only)"
}

Authentication

The API uses JWT-based authentication with access and refresh tokens.

• Access Token: Short-lived (15 minutes), sent in Authorization: Bearer <token> header
• Refresh Token: Long-lived (7 days), stored as bcrypt hash in database
• Passwords are hashed with bcrypt (12 salt rounds)
• Refresh tokens are single-use (rotated on each refresh)

API Endpoints

Health Check

Auth (/api/auth)

POST /register

{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "123456"
}

POST /login

{
  "email": "john@example.com",
  "password": "123456"
}

Returns: { accessToken, refreshToken, user }

POST /refresh-token

{
  "refreshToken": "your_refresh_token"
}

Returns: { accessToken, refreshToken }

Users (/api/users)

PATCH /me (allowed fields: name, phone, avatar, address)

{
  "name": "Updated Name",
  "phone": "+8801711000000",
  "address": {
    "street": "123 Main St",
    "city": "Dhaka",
    "state": "Dhaka",
    "zipCode": "1200",
    "country": "Bangladesh"
  }
}

GET / (query params: page, limit, search)

Categories (/api/categories)

POST /

{
  "name": "Electronics",
  "description":