Local Development

Prerequisites

Before you begin, make sure you have the following installed:

Node.js v20+ (LTS recommended, see .nvmrc)
PostgreSQL 16+ with PostGIS extension
Redis 6+ (or Valkey)
Docker (optional, for containerized services)

Environment Setup

Step 1: Clone the Repository

git clone https://github.com/MechZie/api.git
cd api

Step 2: Install Dependencies

npm install

Step 3: Configure Environment Variables

Copy the example file and fill in your values:

cp .env.example .env

Key variables:

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/mechzie

# Redis
REDIS_URL=redis://localhost:6379

# Firebase (service account credentials)
FIREBASE_PROJECT_ID=your-project-id
FIREBASE_CLIENT_EMAIL=your-client-email
FIREBASE_PRIVATE_KEY="your-private-key"

# JWT
JWT_SECRET=your-jwt-secret-key-here

# AWS S3 (or S3-compatible storage)
AWS_REGION=ap-south-1
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_S3_BUCKET=your-bucket-name

# Razorpay
RAZORPAY_KEY_ID=your-razorpay-key
RAZORPAY_KEY_SECRET=your-razorpay-secret
RAZORPAY_WEBHOOK_SECRET=your-webhook-secret

# Server
PORT=3000
NODE_ENV=development

Never commit your .env file. Use .env.example as a template.

Step 4: Set Up the Database

Run database migrations:

npm run migrate

Seed the database with initial data (optional):

npm run seed

Step 5: Start the Server

For development with auto-reload:

npm run dev

For production build:

npm run build
npm start

Your API should now be running at http://localhost:3000

Docker Setup (Alternative)

Run the entire stack with Docker Compose:

docker-compose up

This starts:

API server on port 3000
PostgreSQL on port 5432
Redis on port 6379

Testing the API

Health Check (Liveness)

curl http://localhost:3000/health

Expected response:

{
  "status": "ok",
  "timestamp": "2026-05-21T10:30:00.000Z",
  "version": "1.0.0-rc1"
}

Readiness Check (DB + Redis)

curl http://localhost:3000/health/ready

Expected response:

{
  "status": "ready",
  "timestamp": "2026-05-21T10:30:00.000Z",
  "checks": {
    "database": { "ok": true, "latencyMs": 2.5 },
    "redis": { "ok": true, "latencyMs": 1.1 }
  }
}

If any dependency is down, returns 503 with "status": "degraded".

Run Tests

# Run all tests
npm test

# Run in watch mode
npm run test:watch

Project Structure

src/
├── modules/           # Feature modules (each has routes, service, validators)
│   ├── auth/          # verify-otp, refresh, logout, admin invite
│   ├── users/         # Profile management
│   ├── vehicles/      # Vehicle CRUD
│   ├── mechanics/     # Registration, availability, documents
│   ├── jobs/          # Job lifecycle, state machine, line items
│   ├── dispatch/      # Auto-dispatch engine (BullMQ)
│   ├── tracking/      # GPS updates, ETA, Socket.io events
│   ├── payments/      # Razorpay integration, webhooks
│   ├── ratings/       # Two-way rating system
│   ├── notifications/ # FCM push, SMS fallback, in-app
│   ├── uploads/       # S3 presigned URL generation
│   └── admin/         # Dashboard, mechanic verification, refunds
├── socket/            # Socket.io server, auth middleware, room helpers
├── queues/            # BullMQ queue definitions
├── workers/           # Background job processors (dispatch, notifications, cleanup)
├── middleware/        # Auth, rate limiting, error handling
├── db/                # Kysely migrations and database setup
├── shared/            # Error codes, constants, utilities
├── index.ts           # Express app setup
└── server.ts          # HTTP server, Socket.io attach, worker startup

Common Tasks

Generate TypeScript Types from Database

npm run generate-types

View Logs

Logs are output to console in development with pretty formatting via pino-pretty. In production, logs are structured JSON (Pino).

Sync OpenAPI Spec to Mintlify Docs

npm run docs:sync

Getting Started

Guides

Development

Prerequisites

Environment Setup

Step 1: Clone the Repository

Step 2: Install Dependencies

Step 3: Configure Environment Variables

Step 4: Set Up the Database

Step 5: Start the Server

Docker Setup (Alternative)

Testing the API

Health Check (Liveness)

Readiness Check (DB + Redis)

Run Tests

Project Structure

Common Tasks

Next Steps

Quickstart

API Reference

​Prerequisites

​Environment Setup

​Step 1: Clone the Repository

​Step 2: Install Dependencies

​Step 3: Configure Environment Variables

​Step 4: Set Up the Database

​Step 5: Start the Server

​Docker Setup (Alternative)

​Testing the API

​Health Check (Liveness)

​Readiness Check (DB + Redis)

​Run Tests

​Project Structure

​Common Tasks

​Next Steps

Quickstart

API Reference

Prerequisites

Environment Setup

Step 1: Clone the Repository

Step 2: Install Dependencies

Step 3: Configure Environment Variables

Step 4: Set Up the Database

Step 5: Start the Server

Docker Setup (Alternative)

Testing the API

Health Check (Liveness)

Readiness Check (DB + Redis)

Run Tests

Project Structure

Common Tasks

Next Steps