FairRelay / DEPLOYMENT.md

MouleeswaranM

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

aeec417 23 days ago

preview code

raw

history blame

10.3 kB

FairRelay — Production Deployment Guide

Architecture Overview

┌─────────────────────────────────────────────────────────────────────┐
│  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/                                                       │
└─────────────────────────────────────────────────────────────────────┘
                                │
┌───────────────────────────────▼─────────────────────────────────────┐
│  Databases                                                          │
│  • PostgreSQL (Render/Supabase) — primary production                │
│  • SQLite fallback (auto-created if no DATABASE_URL)                │
│  • LangSmith (optional tracing)                                     │
│  • Gemini 2.5 Flash (optional LLM explanations)                     │
└─────────────────────────────────────────────────────────────────────┘

Deployment Steps

1. AI Brain (FastAPI) → Render

# 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

Health check URL: /health
API Docs: https://fairrelay-brain.onrender.com/docs

2. Node.js Backend → Render

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

Health check URL: /health

3. Ops Dashboard → Vercel

cd ops/AIsupplychain/aisupply

# 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. Landing Page → Vercel

cd landing

# 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

FairRelay integrates into LoRRI (logisticsnow.in) via:

Option A: API Integration (Recommended)

LoRRI calls FairRelay's allocation API directly:

POST https://fairrelay-backend.onrender.com/api/dispatch/allocate
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "drivers": [...],
  "routes": [...],
  "packages": [...]
}

Option B: Embedded Dashboard

Embed the FairDispatch page in an iframe:

<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

# 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

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