Skip to main content

​
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

npm run generate-types
Logs are output to console in development with pretty formatting via pino-pretty. In production, logs are structured JSON (Pino).
npm run docs:sync

​
Next Steps

Quickstart

Make your first authenticated API request

API Reference

Explore all 56 endpoints