| # 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 |
|
|
| ```bash |
| # 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 |
|
|
| ```bash |
| 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 |
|
|
| ```bash |
| 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 |
|
|
| ```bash |
| 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: |
|
|
| ```bash |
| 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: |
|
|
| ```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 |
| ``` |
|
|
| 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 |
|
|
