docs: Add DEPLOYMENT.md - complete production deployment guide for LoRRI integration

#18
Files changed (1) hide show
  1. DEPLOYMENT.md +210 -166
DEPLOYMENT.md CHANGED
@@ -1,205 +1,249 @@
1
- # 🚀 FairRelay — Production Deployment Guide
2
 
3
- ## Architecture Overview (LoRRI Integration)
4
 
5
  ```
6
  ┌─────────────────────────────────────────────────────────────────────┐
7
- │ LoRRI Production (logisticsnow.in) │
8
- │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
9
- │ │ Indent │ │ Fleet │ │ Trip │ │ E-Way Bill │ │
10
- │ │ Mgmt │ │ Tracking │ │ Mgmt │ │ Generation │ │
11
- │ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────────┬─────────┘ │
12
- │ │ │ │ │ │
13
- │ └──────────────┴──────────────┴──────────────────┘ │
14
- │ │ │
15
- │ ┌─────────▼─────────┐ │
16
- │ │ LoRRI Dispatch │ │
17
- │ │ Module │ │
18
- │ └─────────┬─────────┘ │
19
- └──────────────────────────────┼───────────────────────────────────────┘
20
- │ POST /v1/allocate
21
- │ (API Key Auth)
22
- ▼
23
- ┌─────────────────────────────────────────────────────────────────────┐
24
- │ FairRelay API Gateway (ops/backend-dm) │
25
- │ Render: https://fairrelay-api.onrender.com │
26
- │ │
27
- │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────────┐ │
28
- │ │ /v1/allocate│ │/v1/wellness│ │ /v1/gini │ │/v1/consolidate │ │
29
- │ │ /v1/carbon │ │/v1/night- │ │ /v1/runs │ │/v1/health │ │
30
- │ │ │ │ safety │ │ │ │ │ │
31
- │ └─────┬──────┘ └────────────┘ └────────────┘ └───────┬────────┘ │
32
- │ │ │ │
33
- │ │ Proxies to Brain when available │ │
34
- │ │ Falls back to demo mode otherwise │ │
35
- └────────┼───────────────────────────────────────────────┼────────────┘
36
- │ │
37
- ▼ ▼
38
- ┌─────────────────────────────────────────────────────────────────────┐
39
- │ FairRelay AI Brain (brain/) │
40
- │ Render: https://fairrelay-brain.onrender.com │
41
- │ │
42
- │ ┌─────────────────── LangGraph Workflow ───────────────────────┐ │
43
- │ │ │ │
44
- │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
45
- │ │ │ML Effort │→ │ Route │→ │ Fairness │→ │ Route │ │ │
46
- │ │ │ Agent │ │ Planner │ │ Manager │ │Planner v2│ │ │
47
- │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
48
- │ │ │ │ │ │ │
49
- │ │ ▼ ▼ ▼ │ │
50
- │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
51
- │ │ │ Driver │→ │ Final │→ │Explainab-│→ │ Gemini │ │ │
52
- │ │ │ Liaison │ │Resolution│ │ ility │ │(optional)│ │ │
53
- │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
54
- │ │ │ │
55
- │ └──────────────────────────────────────────────────────────────┘ │
56
- │ │
57
- │ Features: K-Means clustering, OR-Tools optimization, Gini index, │
58
- │ EV-first routing, night safety, recovery days, wellness scoring │
59
  └─────────────────────────────────────────────────────────────────────┘
60
- │
61
- ▼
62
- ┌─────────────────────────────────────────────────────────────────────┐
63
- │ Frontends (Vercel) │
64
- │ │
65
- │ ┌───────────────────┐ ┌───────────────────┐ ┌────────────────┐ │
66
- │ │ Landing Page │ │ Ops Dashboard │ │ Flutter App │ │
67
- │ │ fairrelay.vercel │ │ fairrelay-ops. │ │ MyFairRelay │ │
68
- │ │ .app │ │ vercel.app │ │ (Android/iOS) │ │
69
- │ └───────────────────┘ └───────────────────┘ └────────────────┘ │
70
  └─────────────────────────────────────────────────────────────────────┘
71
  ```
72
 
73
- ## Deploy Commands
 
 
74
 
75
- ### 1. AI Brain (FastAPI + LangGraph) → Render
76
 
77
  ```bash
78
- # From /brain directory
79
- # Render auto-deploys from GitHub via render.yaml
80
-
81
- # Environment variables (set in Render dashboard):
82
- DATABASE_URL= # Leave empty for SQLite fallback (free tier)
83
- APP_ENV=production
84
- GOOGLE_API_KEY= # Optional: enables Gemini explanations
85
- LANGCHAIN_TRACING_V2=false
 
 
 
 
 
 
 
 
86
  ```
87
 
88
- **URL**: `https://fairrelay-brain.onrender.com`
89
- **Health**: `GET /health`
90
- **Docs**: `GET /docs`
91
 
92
- ### 2. API Gateway (Node.js + Prisma) → Render
93
 
94
  ```bash
95
- # From /ops/backend-dm directory
96
- # Deploy as Docker or Node.js service
97
-
98
- # Environment variables:
99
- DATABASE_URL=postgresql://... # Render PostgreSQL (free tier)
100
- BRAIN_URL=https://fairrelay-brain.onrender.com
101
- CORS_ORIGINS=https://fairrelay.vercel.app,https://fairrelay-ops.vercel.app
102
- JWT_SECRET=your-secret-here
103
- NODE_ENV=production
 
 
 
 
 
104
  ```
105
 
106
- **URL**: `https://fairrelay-api.onrender.com`
107
- **Health**: `GET /v1/health`
108
- **Docs**: `GET /api/docs`
109
 
110
- ### 3. Landing Page (React/Vite) → Vercel
111
 
112
  ```bash
113
- cd landing
114
- vercel --prod
115
 
116
- # Environment variables (set in Vercel):
117
- VITE_API_URL=https://fairrelay-api.onrender.com
 
 
 
 
118
  ```
119
 
120
- ### 4. Ops Dashboard (React/Vite) → Vercel
121
 
122
  ```bash
123
- cd ops/AIsupplychain/aisupply
124
- vercel --prod
125
 
126
- # Environment variables:
127
- VITE_API_BASE_URL=https://fairrelay-api.onrender.com
 
 
 
 
128
  ```
129
 
130
- ## LoRRI Integration API Contract
131
 
132
- ### Authentication
133
- ```
134
- Header: x-api-key: fr_live_xxxxxxxxxxxxxxxxxx
135
- ```
136
 
137
- ### Core Endpoint: Fair Allocation
138
- ```http
139
- POST /v1/allocate
 
 
 
140
  Content-Type: application/json
141
- x-api-key: fr_live_xxx
142
 
143
  {
144
- "drivers": [
145
- { "id": "drv_001", "name": "Rajesh Kumar", "hours_today": 4.5, "is_ill": false, "vehicle_type": "DIESEL", "gender": "M" },
146
- { "id": "drv_002", "name": "Priya Sharma", "hours_today": 8.1, "is_ill": false, "vehicle_type": "ELECTRIC", "gender": "F" }
147
- ],
148
- "routes": [
149
- { "id": "rt_A", "distance_km": 142, "difficulty": "medium" },
150
- { "id": "rt_B", "distance_km": 48, "difficulty": "easy", "is_city_centre": true }
151
- ],
152
- "options": { "ev_first": true, "night_safety": true }
153
  }
154
  ```
155
 
156
- **Response:**
157
- ```json
158
- {
159
- "success": true,
160
- "data": {
161
- "id": "run_1708394400000",
162
- "allocations": [
163
- {
164
- "driver": "drv_002",
165
- "route": "rt_B",
166
- "wellness_score": 61,
167
- "carbon_kg": "10.1",
168
- "explanation": "Priya assigned city route (EV-first). 8.1h worked — shorter route for recovery."
169
- }
170
- ]
171
- },
172
- "meta": {
173
- "gini_index": 0.12,
174
- "fairness_grade": "A",
175
- "carbon_kg": "39.8",
176
- "latency_ms": 284,
177
- "mode": "live"
178
- }
179
- }
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
180
  ```
181
 
182
- ### Other Endpoints
183
- | Endpoint | Method | Description |
184
- |----------|--------|-------------|
185
- | `/v1/health` | GET | System + Brain connectivity |
186
- | `/v1/allocate` | POST | Fair route allocation |
187
- | `/v1/wellness` | POST | Driver wellness scoring |
188
- | `/v1/gini` | POST | Standalone Gini calculation |
189
- | `/v1/night-safety` | POST | Night safety constraints |
190
- | `/v1/carbon` | POST | CO₂ emission estimates |
191
- | `/v1/consolidate` | POST | AI load consolidation |
192
- | `/v1/runs` | GET | Recent allocation history |
193
-
194
- ## What Makes This YC-Level
195
-
196
- 1. **Real AI Pipeline** — 6-8 LangGraph agents with OR-Tools optimization (not mock data)
197
- 2. **Fairness Metrics** — Gini coefficient computed per run, tracked over time
198
- 3. **SDG Alignment** — SDG 8 (Decent Work), SDG 10 (Inequality), SDG 13 (Climate)
199
- 4. **Production Architecture** — API gateway + microservice brain + SSE streaming
200
- 5. **Explainability** — Every allocation decision has a human-readable explanation
201
- 6. **Driver Wellness** — Fatigue scoring, recovery days, night safety for women
202
- 7. **EV-First Routing** — Prioritizes electric vehicles for city-centre routes
203
- 8. **Learning Agent** — Multi-armed bandit tunes fairness thresholds over time
204
- 9. **LoRRI Integration** — Single API call from existing TMS, zero disruption
205
- 10. **Scale** — K-Means + OR-Tools handles 1000+ packages in <5s
 
1
+ # FairRelay — Production Deployment Guide
2
 
3
+ ## Architecture Overview
4
 
5
  ```
6
  ┌─────────────────────────────────────────────────────────────────────┐
7
+ │ LoRRI Production (logisticsnow.in) │
8
+ │ Embeds FairRelay via iframe/API integration │
9
+ └───────────────────────────────┬─────────────────────────────────────┘
10
+ │ HTTPS
11
+ ┌───────────────────────────────▼─────────────────────────────────────┐
12
+ │ Ops Dashboard (Vercel) │
13
+ │ React + Vite + TailwindCSS │
14
+ │ Pages: FairDispatch, LoadConsolidation, AssignTasks, Analytics │
15
+ │ URL: https://fairrelay.vercel.app │
16
+ │ Root: ops/AIsupplychain/aisupply/ │
17
+ └───────────────────────────────┬─────────────────────────────────────┘
18
+ │ HTTPS (axios → /api/*)
19
+ ┌───────────────────────────────▼─────────────────────────────────────┐
20
+ │ Node.js API Gateway (Render) │
21
+ │ Express + Prisma + Socket.IO │
22
+ │ Auth, Drivers CRUD, Packages, E-Way Bills, Carbon, Wellness │
23
+ │ Proxies /api/dispatch/* → Brain │
24
+ │ URL: https://fairrelay-backend.onrender.com │
25
+ │ Root: ops/backend-dm/ │
26
+ └───────────────────────────────┬─────────────────────────────────────┘
27
+ │ HTTPS (proxy)
28
+ ┌───────────────────────────────▼─────────────────────────────────────┐
29
+ │ AI Brain (Render - Docker) │
30
+ │ FastAPI + LangGraph + SQLAlchemy │
31
+ │ 8 AI Agents: ML Effort → Route Planner → Fairness Manager → │
32
+ │ Driver Liaison → Final Resolution → Explainability → Learning │
33
+ │ + 5-Agent Consolidation Pipeline │
34
+ │ URL: https://fairrelay-brain.onrender.com │
35
+ │ Root: brain/ │
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
36
  └─────────────────────────────────────────────────────────────────────┘
37
+ │
38
+ ┌───────────────────────────────▼─────────────────────────────────────┐
39
+ │ Databases │
40
+ │ • PostgreSQL (Render/Supabase) — primary production │
41
+ │ • SQLite fallback (auto-created if no DATABASE_URL) │
42
+ │ • LangSmith (optional tracing) │
43
+ │ • Gemini 2.5 Flash (optional LLM explanations) │
 
 
 
44
  └─────────────────────────────────────────────────────────────────────┘
45
  ```
46
 
47
+ ---
48
+
49
+ ## Deployment Steps
50
 
51
+ ### 1. AI Brain (FastAPI) → Render
52
 
53
  ```bash
54
+ # From the brain/ directory
55
+ cd brain
56
+
57
+ # Deploy to Render:
58
+ # 1. Create New Web Service → Docker
59
+ # 2. Root Directory: brain
60
+ # 3. Dockerfile Path: ./Dockerfile
61
+ # 4. Environment Variables:
62
+ # APP_ENV=production
63
+ # PORT=8000
64
+ # DATABASE_URL= (leave empty for SQLite fallback)
65
+ # CORS_ORIGINS=https://fairrelay-backend.onrender.com,https://fairrelay.vercel.app,https://logisticsnow.in
66
+ # GOOGLE_API_KEY=<your-key> (optional, for Gemini explanations)
67
+ # GEMINI_MODEL=gemini-2.5-flash
68
+ # ENABLE_GEMINI_EXPLAIN=true
69
+ # LANGCHAIN_TRACING_V2=false
70
  ```
71
 
72
+ **Health check URL:** `/health`
73
+ **API Docs:** `https://fairrelay-brain.onrender.com/docs`
 
74
 
75
+ ### 2. Node.js Backend → Render
76
 
77
  ```bash
78
+ cd ops/backend-dm
79
+
80
+ # Deploy to Render:
81
+ # 1. Create New Web Service → Node
82
+ # 2. Root Directory: ops/backend-dm
83
+ # 3. Build Command: npm install
84
+ # 4. Start Command: node index.js
85
+ # 5. Environment Variables:
86
+ # NODE_ENV=production
87
+ # PORT=3000
88
+ # BRAIN_URL=https://fairrelay-brain.onrender.com
89
+ # DATABASE_URL=<your-postgres-url>
90
+ # JWT_SECRET=<random-secure-string>
91
+ # CORS_ORIGINS=https://fairrelay.vercel.app,https://logisticsnow.in
92
  ```
93
 
94
+ **Health check URL:** `/health`
 
 
95
 
96
+ ### 3. Ops Dashboard → Vercel
97
 
98
  ```bash
99
+ cd ops/AIsupplychain/aisupply
 
100
 
101
+ # Deploy to Vercel:
102
+ # 1. Import from GitHub
103
+ # 2. Root Directory: ops/AIsupplychain/aisupply
104
+ # 3. Framework: Vite
105
+ # 4. Environment Variables:
106
+ # VITE_API_URL=https://fairrelay-backend.onrender.com
107
  ```
108
 
109
+ ### 4. Landing Page → Vercel
110
 
111
  ```bash
112
+ cd landing
 
113
 
114
+ # Deploy to Vercel:
115
+ # 1. Import from GitHub
116
+ # 2. Root Directory: landing
117
+ # 3. Framework: Vite
118
+ # 4. Environment Variables:
119
+ # VITE_API_URL=https://fairrelay-backend.onrender.com
120
  ```
121
 
122
+ ---
123
 
124
+ ## LoRRI Integration
125
+
126
+ FairRelay integrates into LoRRI (logisticsnow.in) via:
 
127
 
128
+ ### Option A: API Integration (Recommended)
129
+ LoRRI calls FairRelay's allocation API directly:
130
+
131
+ ```bash
132
+ POST https://fairrelay-backend.onrender.com/api/dispatch/allocate
133
+ Authorization: Bearer <jwt-token>
134
  Content-Type: application/json
 
135
 
136
  {
137
+ "drivers": [...],
138
+ "routes": [...],
139
+ "packages": [...]
 
 
 
 
 
 
140
  }
141
  ```
142
 
143
+ ### Option B: Embedded Dashboard
144
+ Embed the FairDispatch page in an iframe:
145
+
146
+ ```html
147
+ <iframe src="https://fairrelay.vercel.app/fair-dispatch"
148
+ width="100%" height="800px"
149
+ frameborder="0" allow="clipboard-read">
150
+ </iframe>
151
+ ```
152
+
153
+ ### Option C: Webhook Integration
154
+ LoRRI sends webhook events → FairRelay processes → returns results:
155
+
156
+ ```
157
+ LoRRI → POST /api/v1/allocate (with drivers + packages)
158
+ ← Response with fair assignments + explanations
159
+ → POST /api/v1/consolidate/optimize (with shipments + trucks)
160
+ ← Response with consolidated groups + carbon savings
161
+ ```
162
+
163
+ ---
164
+
165
+ ## AI Agent Pipeline (What runs on each allocation)
166
+
167
+ | Phase | Agent | What it does | Latency |
168
+ |-------|-------|-------------|---------|
169
+ | 1 | ML Effort Agent | Builds [drivers × routes] effort matrix | ~50ms |
170
+ | 2 | Route Planner | OR-Tools linear assignment (proposal 1) | ~100ms |
171
+ | 3a | Fairness Manager | Evaluates Gini/stddev/max_gap | ~20ms |
172
+ | 3b | Route Planner (re-opt) | Penalized assignment if unfair | ~80ms |
173
+ | 4 | Driver Liaison | Per-driver comfort band negotiation | ~30ms |
174
+ | 5 | Final Resolution | Resolves counter-proposals via swaps | ~50ms |
175
+ | 6 | Explainability | Generates natural language explanations | ~100ms |
176
+ | 6b | Gemini LLM (optional) | Rich multilingual explanations | ~2s |
177
+ | 7 | Learning Agent | Creates episode for config auto-tuning | ~10ms |
178
+
179
+ **Total pipeline:** ~450ms (without Gemini) / ~2.5s (with Gemini)
180
+
181
+ ---
182
+
183
+ ## Environment Variables Reference
184
+
185
+ ### Brain (FastAPI)
186
+ | Variable | Required | Default | Description |
187
+ |----------|----------|---------|-------------|
188
+ | `DATABASE_URL` | No | SQLite | PostgreSQL URL or empty for SQLite |
189
+ | `APP_ENV` | No | production | `development` or `production` |
190
+ | `GOOGLE_API_KEY` | No | — | Gemini API key for LLM explanations |
191
+ | `GEMINI_MODEL` | No | gemini-2.5-flash | Model for explanations |
192
+ | `ENABLE_GEMINI_EXPLAIN` | No | false | Enable Gemini agent |
193
+ | `LANGCHAIN_API_KEY` | No | — | LangSmith tracing key |
194
+ | `CORS_ORIGINS` | No | * | Comma-separated allowed origins |
195
+
196
+ ### Backend (Node.js)
197
+ | Variable | Required | Default | Description |
198
+ |----------|----------|---------|-------------|
199
+ | `DATABASE_URL` | Yes* | — | PostgreSQL for auth/drivers/packages |
200
+ | `BRAIN_URL` | Yes | localhost:8000 | URL of the AI brain service |
201
+ | `JWT_SECRET` | Yes | — | Secret for JWT token signing |
202
+ | `CORS_ORIGINS` | No | localhost | Allowed CORS origins |
203
+ | `PORT` | No | 3000 | Server port |
204
+
205
+ ### Dashboard (React)
206
+ | Variable | Required | Default | Description |
207
+ |----------|----------|---------|-------------|
208
+ | `VITE_API_URL` | Yes | /api | Backend URL (Render) |
209
+
210
+ ---
211
+
212
+ ## Local Development
213
+
214
+ ```bash
215
+ # Terminal 1: AI Brain
216
+ cd brain
217
+ pip install -r requirements.txt
218
+ uvicorn app.main:app --reload --port 8000
219
+
220
+ # Terminal 2: Node.js Backend
221
+ cd ops/backend-dm
222
+ npm install
223
+ echo "BRAIN_URL=http://localhost:8000" > .env
224
+ node index.js
225
+
226
+ # Terminal 3: Ops Dashboard
227
+ cd ops/AIsupplychain/aisupply
228
+ npm install
229
+ echo "VITE_API_URL=http://localhost:3000" > .env
230
+ npm run dev
231
  ```
232
 
233
+ Open http://localhost:5173 → FairDispatch page → Run Fair Allocation
234
+
235
+ ---
236
+
237
+ ## Production Checklist
238
+
239
+ - [ ] Brain deployed on Render (Docker) ✓ Health check passes
240
+ - [ ] Node.js backend on Render ✓ `/health` returns healthy
241
+ - [ ] Dashboard on Vercel ✓ Connects to backend
242
+ - [ ] PostgreSQL database provisioned (Render/Supabase)
243
+ - [ ] `BRAIN_URL` in backend points to brain service
244
+ - [ ] `VITE_API_URL` in dashboard points to backend
245
+ - [ ] CORS origins include `logisticsnow.in`
246
+ - [ ] Gemini API key configured (optional but recommended)
247
+ - [ ] SSL/HTTPS on all services (automatic on Render/Vercel)
248
+ - [ ] Rate limiting active on auth endpoints
249
+ - [ ] Socket.IO CORS configured for real-time updates