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

# MechZie API Documentation

> Internal API docs for the MechZie roadside mechanic dispatch service — for frontend devs and AI-assisted development

## Welcome to MechZie API

MechZie is an on-demand roadside mechanic dispatch service. This documentation covers the backend API for **internal frontend developers** building the Flutter customer and mechanic apps.

<Tip>
  These docs are optimized for AI-assisted development. Copy any page into your IDE's AI assistant (Cursor, Copilot, etc.) for accurate code generation against the MechZie API.
</Tip>

<Card title="Quickstart — First API Call in 5 Minutes" icon="rocket" href="/quickstart" horizontal>
  Firebase auth → JWT exchange → your first request.
</Card>

## Guides

<Columns cols={2}>
  <Card title="Authentication" icon="shield" href="/authentication">
    Firebase Phone OTP → JWT tokens, refresh flow, admin invites, role system.
  </Card>

  <Card title="Real-time Events" icon="bolt" href="/realtime">
    Socket.io setup, live mechanic tracking, dispatch offers, room management.
  </Card>

  <Card title="Job Lifecycle" icon="clipboard-list" href="/job-lifecycle">
    State machine, dispatch tiers, line items, cancellation fees.
  </Card>

  <Card title="Payments" icon="credit-card" href="/payments">
    Razorpay integration, payment flow, webhooks, pricing in paisa.
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/error-handling">
    Error codes, rate limits, pagination, validation errors.
  </Card>

  <Card title="File Uploads" icon="cloud-arrow-up" href="/file-uploads">
    S3 presigned URL flow for photos and documents.
  </Card>

  <Card title="Notifications" icon="bell" href="/notifications">
    FCM push setup, in-app notifications, deep-linking.
  </Card>

  <Card title="Local Development" icon="code" href="/development">
    Clone, install, run the API locally with Docker.
  </Card>
</Columns>

## API Reference

<Card title="REST API Reference — 56 Endpoints" icon="book" href="/api-reference" horizontal>
  Interactive endpoint explorer with request/response examples. Covers auth, users, vehicles, jobs, mechanics, payments, ratings, notifications, uploads, admin, and super-admin.
</Card>

## API at a Glance

| Area              | Endpoints              | Key Features                                     |
| ----------------- | ---------------------- | ------------------------------------------------ |
| **Auth**          | 4                      | Firebase OTP → JWT, token refresh, admin invites |
| **Jobs**          | 13                     | Full lifecycle, line items, state machine        |
| **Mechanics**     | 6                      | Registration, availability, location, documents  |
| **Payments**      | 6                      | Razorpay orders, verification, webhooks, fees    |
| **Tracking**      | 1 + 9 Socket.io events | Live GPS, ETA, dispatch offers                   |
| **Notifications** | 4                      | FCM push, in-app list, mark read                 |
| **Uploads**       | 1                      | S3 presigned URLs                                |
| **Ratings**       | 3                      | Two-way ratings, 7-day window                    |
| **Admin**         | 13                     | Dashboard, mechanic verification, refunds        |

## Client SDK Requirements

Your Flutter app needs these packages to integrate with the API:

| Package                  | Purpose                              |
| ------------------------ | ------------------------------------ |
| `firebase_auth`          | Phone OTP authentication             |
| `socket_io_client`       | Real-time events (NOT raw WebSocket) |
| `razorpay_flutter`       | Payment checkout                     |
| `firebase_messaging`     | Push notifications                   |
| `flutter_secure_storage` | Token storage                        |