> ## Documentation Index
> Fetch the complete documentation index at: https://internal.mechzie.in/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Local Development

> Set up and run the MechZie API locally

## 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

```bash theme={null}
git clone https://github.com/MechZie/api.git
cd api
```

### Step 2: Install Dependencies

```bash theme={null}
npm install
```

### Step 3: Configure Environment Variables

Copy the example file and fill in your values:

```bash theme={null}
cp .env.example .env
```

Key variables:

```bash theme={null}
# 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
```

<Warning>
  Never commit your `.env` file. Use `.env.example` as a template.
</Warning>

### Step 4: Set Up the Database

Run database migrations:

```bash theme={null}
npm run migrate
```

Seed the database with initial data (optional):

```bash theme={null}
npm run seed
```

### Step 5: Start the Server

For development with auto-reload:

```bash theme={null}
npm run dev
```

For production build:

```bash theme={null}
npm run build
npm start
```

<Check>
  Your API should now be running at `http://localhost:3000`
</Check>

## Docker Setup (Alternative)

Run the entire stack with Docker Compose:

```bash theme={null}
docker-compose up
```

This starts:

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

## Testing the API

### Health Check (Liveness)

```bash theme={null}
curl http://localhost:3000/health
```

Expected response:

```json theme={null}
{
  "status": "ok",
  "timestamp": "2026-05-21T10:30:00.000Z",
  "version": "1.0.0-rc1"
}
```

### Readiness Check (DB + Redis)

```bash theme={null}
curl http://localhost:3000/health/ready
```

Expected response:

```json theme={null}
{
  "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

```bash theme={null}
# 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

<AccordionGroup>
  <Accordion title="Generate TypeScript Types from Database">
    ```bash theme={null}
    npm run generate-types
    ```
  </Accordion>

  <Accordion title="View Logs">
    Logs are output to console in development with pretty formatting via `pino-pretty`.
    In production, logs are structured JSON (Pino).
  </Accordion>

  <Accordion title="Sync OpenAPI Spec to Mintlify Docs">
    ```bash theme={null}
    npm run docs:sync
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Make your first authenticated API request
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference">
    Explore all 56 endpoints
  </Card>
</CardGroup>