docs: Add DEPLOYMENT.md - complete production deployment guide for LoRRI integration (#18)

- docs: Add DEPLOYMENT.md - complete production deployment guide for LoRRI integration (0c1769796e4d38b4e58d355a2e13c5f8b9a78cf1)

DEPLOYMENT.md

@@ -1,205 +1,249 @@
-# 🚀 FairRelay — Production Deployment Guide
+# FairRelay — Production Deployment Guide
 
-## Architecture Overview (LoRRI Integration)
+## Architecture Overview
 
 ```
 ┌─────────────────────────────────────────────────────────────────────┐
-│                    LoRRI Production (logisticsnow.in)                │
-│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────────┐   │
-│  │ Indent   │  │  Fleet   │  │  Trip    │  │  E-Way Bill      │   │
-│  │ Mgmt     │  │ Tracking │  │  Mgmt    │  │  Generation      │   │
-│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────────┬─────────┘   │
-│       │              │              │                  │             │
-│       └──────────────┴──────────────┴──────────────────┘             │
-│                              │                                       │
-│                    ┌─────────▼─────────┐                             │
-│                    │  LoRRI Dispatch   │                             │
-│                    │  Module           │                             │
-│                    └─────────┬─────────┘                             │
-└──────────────────────────────┼───────────────────────────────────────┘
-                               │ POST /v1/allocate
-                               │ (API Key Auth)
-                               ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│              FairRelay API Gateway (ops/backend-dm)                  │
-│              Render: https://fairrelay-api.onrender.com              │
-│                                                                     │
-│  ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────────┐  │
-│  │ /v1/allocate│ │/v1/wellness│ │ /v1/gini   │ │/v1/consolidate │  │
-│  │ /v1/carbon │ │/v1/night-  │ │ /v1/runs   │ │/v1/health      │  │
-│  │            │ │  safety    │ │            │ │                │  │
-│  └─────┬──────┘ └────────────┘ └────────────┘ └───────┬────────┘  │
-│        │                                               │            │
-│        │  Proxies to Brain when available               │            │
-│        │  Falls back to demo mode otherwise             │            │
-└────────┼───────────────────────────────────────────────┼────────────┘
-         │                                               │
-         ▼                                               ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│              FairRelay AI Brain (brain/)                             │
-│              Render: https://fairrelay-brain.onrender.com            │
-│                                                                     │
-│  ┌─────────────────── LangGraph Workflow ───────────────────────┐   │
-│  │                                                              │   │
-│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │   │
-│  │  │ML Effort │→ │  Route   │→ │ Fairness │→ │  Route   │   │   │
-│  │  │  Agent   │  │ Planner  │  │ Manager  │  │Planner v2│   │   │
-│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │   │
-│  │       │                            │              │          │   │
-│  │       ▼                            ▼              ▼          │   │
-│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │   │
-│  │  │ Driver   │→ │  Final   │→ │Explainab-│→ │  Gemini  │   │   │
-│  │  │ Liaison  │  │Resolution│  │  ility   │  │(optional)│   │   │
-│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │   │
-│  │                                                              │   │
-│  └──────────────────────────────────────────────────────────────┘   │
-│                                                                     │
-│  Features: K-Means clustering, OR-Tools optimization, Gini index,  │
-│  EV-first routing, night safety, recovery days, wellness scoring    │
+│  LoRRI Production (logisticsnow.in)                                 │
+│  Embeds FairRelay via iframe/API integration                        │
+└───────────────────────────────┬─────────────────────────────────────┘
+                                │ HTTPS
+┌───────────────────────────────▼─────────────────────────────────────┐
+│  Ops Dashboard (Vercel)                                             │
+│  React + Vite + TailwindCSS                                        │
+│  Pages: FairDispatch, LoadConsolidation, AssignTasks, Analytics     │
+│  URL: https://fairrelay.vercel.app                                  │
+│  Root: ops/AIsupplychain/aisupply/                                  │
+└───────────────────────────────┬─────────────────────────────────────┘
+                                │ HTTPS (axios → /api/*)
+┌───────────────────────────────▼─────────────────────────────────────┐
+│  Node.js API Gateway (Render)                                       │
+│  Express + Prisma + Socket.IO                                       │
+│  Auth, Drivers CRUD, Packages, E-Way Bills, Carbon, Wellness        │
+│  Proxies /api/dispatch/* → Brain                                    │
+│  URL: https://fairrelay-backend.onrender.com                        │
+│  Root: ops/backend-dm/                                              │
+└───────────────────────────────┬─────────────────────────────────────┘
+                                │ HTTPS (proxy)
+┌───────────────────────────────▼─────────────────────────────────────┐
+│  AI Brain (Render - Docker)                                         │
+│  FastAPI + LangGraph + SQLAlchemy                                   │
+│  8 AI Agents: ML Effort → Route Planner → Fairness Manager →       │
+│  Driver Liaison → Final Resolution → Explainability → Learning      │
+│  + 5-Agent Consolidation Pipeline                                   │
+│  URL: https://fairrelay-brain.onrender.com                          │
+│  Root: brain/                                                       │
 └─────────────────────────────────────────────────────────────────────┘
-         │
-         ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│  Frontends (Vercel)                                                 │
-│                                                                     │
-│  ┌───────────────────┐  ┌───────────────────┐  ┌────────────────┐ │
-│  │ Landing Page      │  │ Ops Dashboard     │  │ Flutter App    │ │
-│  │ fairrelay.vercel  │  │ fairrelay-ops.    │  │ MyFairRelay    │ │
-│  │ .app              │  │ vercel.app        │  │ (Android/iOS)  │ │
-│  └───────────────────┘  └───────────────────┘  └────────────────┘ │
+                                │
+┌───────────────────────────────▼─────────────────────────────────────┐
+│  Databases                                                          │
+│  • PostgreSQL (Render/Supabase) — primary production                │
+│  • SQLite fallback (auto-created if no DATABASE_URL)                │
+│  • LangSmith (optional tracing)                                     │
+│  • Gemini 2.5 Flash (optional LLM explanations)                     │
 └─────────────────────────────────────────────────────────────────────┘
 ```
 
-## Deploy Commands
+---
+
+## Deployment Steps
 
-### 1. AI Brain (FastAPI + LangGraph) → Render
+### 1. AI Brain (FastAPI) → Render
 
 ```bash
-# From /brain directory
-# Render auto-deploys from GitHub via render.yaml
-
-# Environment variables (set in Render dashboard):
-DATABASE_URL=            # Leave empty for SQLite fallback (free tier)
-APP_ENV=production
-GOOGLE_API_KEY=          # Optional: enables Gemini explanations
-LANGCHAIN_TRACING_V2=false
+# From the brain/ directory
+cd brain
+
+# Deploy to Render:
+# 1. Create New Web Service → Docker
+# 2. Root Directory: brain
+# 3. Dockerfile Path: ./Dockerfile
+# 4. Environment Variables:
+#    APP_ENV=production
+#    PORT=8000
+#    DATABASE_URL=             (leave empty for SQLite fallback)
+#    CORS_ORIGINS=https://fairrelay-backend.onrender.com,https://fairrelay.vercel.app,https://logisticsnow.in
+#    GOOGLE_API_KEY=<your-key> (optional, for Gemini explanations)
+#    GEMINI_MODEL=gemini-2.5-flash
+#    ENABLE_GEMINI_EXPLAIN=true
+#    LANGCHAIN_TRACING_V2=false
 ```
 
-**URL**: `https://fairrelay-brain.onrender.com`
-**Health**: `GET /health`
-**Docs**: `GET /docs`
+**Health check URL:** `/health`  
+**API Docs:** `https://fairrelay-brain.onrender.com/docs`
 
-### 2. API Gateway (Node.js + Prisma) → Render
+### 2. Node.js Backend → Render
 
 ```bash
-# From /ops/backend-dm directory
-# Deploy as Docker or Node.js service
-
-# Environment variables:
-DATABASE_URL=postgresql://...  # Render PostgreSQL (free tier)
-BRAIN_URL=https://fairrelay-brain.onrender.com
-CORS_ORIGINS=https://fairrelay.vercel.app,https://fairrelay-ops.vercel.app
-JWT_SECRET=your-secret-here
-NODE_ENV=production
+cd ops/backend-dm
+
+# Deploy to Render:
+# 1. Create New Web Service → Node
+# 2. Root Directory: ops/backend-dm
+# 3. Build Command: npm install
+# 4. Start Command: node index.js
+# 5. Environment Variables:
+#    NODE_ENV=production
+#    PORT=3000
+#    BRAIN_URL=https://fairrelay-brain.onrender.com
+#    DATABASE_URL=<your-postgres-url>
+#    JWT_SECRET=<random-secure-string>
+#    CORS_ORIGINS=https://fairrelay.vercel.app,https://logisticsnow.in
 ```
 
-**URL**: `https://fairrelay-api.onrender.com`
-**Health**: `GET /v1/health`
-**Docs**: `GET /api/docs`
+**Health check URL:** `/health`
 
-### 3. Landing Page (React/Vite) → Vercel
+### 3. Ops Dashboard → Vercel
 
 ```bash
-cd landing
-vercel --prod
+cd ops/AIsupplychain/aisupply
 
-# Environment variables (set in Vercel):
-VITE_API_URL=https://fairrelay-api.onrender.com
+# Deploy to Vercel:
+# 1. Import from GitHub
+# 2. Root Directory: ops/AIsupplychain/aisupply
+# 3. Framework: Vite
+# 4. Environment Variables:
+#    VITE_API_URL=https://fairrelay-backend.onrender.com
 ```
 
-### 4. Ops Dashboard (React/Vite) → Vercel
+### 4. Landing Page → Vercel
 
 ```bash
-cd ops/AIsupplychain/aisupply
-vercel --prod
+cd landing
 
-# Environment variables:
-VITE_API_BASE_URL=https://fairrelay-api.onrender.com
+# Deploy to Vercel:
+# 1. Import from GitHub
+# 2. Root Directory: landing
+# 3. Framework: Vite
+# 4. Environment Variables:
+#    VITE_API_URL=https://fairrelay-backend.onrender.com
 ```
 
-## LoRRI Integration API Contract
+---
 
-### Authentication
-```
-Header: x-api-key: fr_live_xxxxxxxxxxxxxxxxxx
-```
+## LoRRI Integration
+
+FairRelay integrates into LoRRI (logisticsnow.in) via:
 
-### Core Endpoint: Fair Allocation
-```http
-POST /v1/allocate
+### Option A: API Integration (Recommended)
+LoRRI calls FairRelay's allocation API directly:
+
+```bash
+POST https://fairrelay-backend.onrender.com/api/dispatch/allocate
+Authorization: Bearer <jwt-token>
 Content-Type: application/json
-x-api-key: fr_live_xxx
 
 {
-  "drivers": [
-    { "id": "drv_001", "name": "Rajesh Kumar", "hours_today": 4.5, "is_ill": false, "vehicle_type": "DIESEL", "gender": "M" },
-    { "id": "drv_002", "name": "Priya Sharma", "hours_today": 8.1, "is_ill": false, "vehicle_type": "ELECTRIC", "gender": "F" }
-  ],
-  "routes": [
-    { "id": "rt_A", "distance_km": 142, "difficulty": "medium" },
-    { "id": "rt_B", "distance_km": 48, "difficulty": "easy", "is_city_centre": true }
-  ],
-  "options": { "ev_first": true, "night_safety": true }
+  "drivers": [...],
+  "routes": [...],
+  "packages": [...]
 }
 ```
 
-**Response:**
-```json
-{
-  "success": true,
-  "data": {
-    "id": "run_1708394400000",
-    "allocations": [
-      {
-        "driver": "drv_002",
-        "route": "rt_B",
-        "wellness_score": 61,
-        "carbon_kg": "10.1",
-        "explanation": "Priya assigned city route (EV-first). 8.1h worked — shorter route for recovery."
-      }
-    ]
-  },
-  "meta": {
-    "gini_index": 0.12,
-    "fairness_grade": "A",
-    "carbon_kg": "39.8",
-    "latency_ms": 284,
-    "mode": "live"
-  }
-}
+### Option B: Embedded Dashboard
+Embed the FairDispatch page in an iframe:
+
+```html
+<iframe src="https://fairrelay.vercel.app/fair-dispatch" 
+        width="100%" height="800px" 
+        frameborder="0" allow="clipboard-read">
+</iframe>
+```
+
+### Option C: Webhook Integration
+LoRRI sends webhook events → FairRelay processes → returns results:
+
+```
+LoRRI → POST /api/v1/allocate (with drivers + packages)
+     ← Response with fair assignments + explanations
+     → POST /api/v1/consolidate/optimize (with shipments + trucks)
+     ← Response with consolidated groups + carbon savings
+```
+
+---
+
+## AI Agent Pipeline (What runs on each allocation)
+
+| Phase | Agent | What it does | Latency |
+|-------|-------|-------------|---------|
+| 1 | ML Effort Agent | Builds [drivers × routes] effort matrix | ~50ms |
+| 2 | Route Planner | OR-Tools linear assignment (proposal 1) | ~100ms |
+| 3a | Fairness Manager | Evaluates Gini/stddev/max_gap | ~20ms |
+| 3b | Route Planner (re-opt) | Penalized assignment if unfair | ~80ms |
+| 4 | Driver Liaison | Per-driver comfort band negotiation | ~30ms |
+| 5 | Final Resolution | Resolves counter-proposals via swaps | ~50ms |
+| 6 | Explainability | Generates natural language explanations | ~100ms |
+| 6b | Gemini LLM (optional) | Rich multilingual explanations | ~2s |
+| 7 | Learning Agent | Creates episode for config auto-tuning | ~10ms |
+
+**Total pipeline:** ~450ms (without Gemini) / ~2.5s (with Gemini)
+
+---
+
+## Environment Variables Reference
+
+### Brain (FastAPI)
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `DATABASE_URL` | No | SQLite | PostgreSQL URL or empty for SQLite |
+| `APP_ENV` | No | production | `development` or `production` |
+| `GOOGLE_API_KEY` | No | — | Gemini API key for LLM explanations |
+| `GEMINI_MODEL` | No | gemini-2.5-flash | Model for explanations |
+| `ENABLE_GEMINI_EXPLAIN` | No | false | Enable Gemini agent |
+| `LANGCHAIN_API_KEY` | No | — | LangSmith tracing key |
+| `CORS_ORIGINS` | No | * | Comma-separated allowed origins |
+
+### Backend (Node.js)
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `DATABASE_URL` | Yes* | — | PostgreSQL for auth/drivers/packages |
+| `BRAIN_URL` | Yes | localhost:8000 | URL of the AI brain service |
+| `JWT_SECRET` | Yes | — | Secret for JWT token signing |
+| `CORS_ORIGINS` | No | localhost | Allowed CORS origins |
+| `PORT` | No | 3000 | Server port |
+
+### Dashboard (React)
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `VITE_API_URL` | Yes | /api | Backend URL (Render) |
+
+---
+
+## Local Development
+
+```bash
+# Terminal 1: AI Brain
+cd brain
+pip install -r requirements.txt
+uvicorn app.main:app --reload --port 8000
+
+# Terminal 2: Node.js Backend
+cd ops/backend-dm
+npm install
+echo "BRAIN_URL=http://localhost:8000" > .env
+node index.js
+
+# Terminal 3: Ops Dashboard
+cd ops/AIsupplychain/aisupply
+npm install
+echo "VITE_API_URL=http://localhost:3000" > .env
+npm run dev
 ```
 
-### Other Endpoints
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/v1/health` | GET | System + Brain connectivity |
-| `/v1/allocate` | POST | Fair route allocation |
-| `/v1/wellness` | POST | Driver wellness scoring |
-| `/v1/gini` | POST | Standalone Gini calculation |
-| `/v1/night-safety` | POST | Night safety constraints |
-| `/v1/carbon` | POST | CO₂ emission estimates |
-| `/v1/consolidate` | POST | AI load consolidation |
-| `/v1/runs` | GET | Recent allocation history |
-
-## What Makes This YC-Level
-
-1. **Real AI Pipeline** — 6-8 LangGraph agents with OR-Tools optimization (not mock data)
-2. **Fairness Metrics** — Gini coefficient computed per run, tracked over time
-3. **SDG Alignment** — SDG 8 (Decent Work), SDG 10 (Inequality), SDG 13 (Climate)
-4. **Production Architecture** — API gateway + microservice brain + SSE streaming
-5. **Explainability** — Every allocation decision has a human-readable explanation
-6. **Driver Wellness** — Fatigue scoring, recovery days, night safety for women
-7. **EV-First Routing** — Prioritizes electric vehicles for city-centre routes
-8. **Learning Agent** — Multi-armed bandit tunes fairness thresholds over time
-9. **LoRRI Integration** — Single API call from existing TMS, zero disruption
-10. **Scale** — K-Means + OR-Tools handles 1000+ packages in <5s
+Open http://localhost:5173 → FairDispatch page → Run Fair Allocation
+
+---
+
+## Production Checklist
+
+- [ ] Brain deployed on Render (Docker) ✓ Health check passes
+- [ ] Node.js backend on Render ✓ `/health` returns healthy
+- [ ] Dashboard on Vercel ✓ Connects to backend
+- [ ] PostgreSQL database provisioned (Render/Supabase)
+- [ ] `BRAIN_URL` in backend points to brain service
+- [ ] `VITE_API_URL` in dashboard points to backend
+- [ ] CORS origins include `logisticsnow.in`
+- [ ] Gemini API key configured (optional but recommended)
+- [ ] SSL/HTTPS on all services (automatic on Render/Vercel)
+- [ ] Rate limiting active on auth endpoints
+- [ ] Socket.IO CORS configured for real-time updates