🚛 LogiPulse // Autonomous Supply Chain Crisis Orchestrator

CI/CD Tests Vercel Python FastAPI LangGraph Gemini React Three.js TailwindCSS Tech Zephyr 4.0 Team Arkz

Self-healing logistics networks powered by LangGraph, Google Gemini, OpenRouteService, and OpenWeatherMap.
Built for Tech Zephyr 4.0 at IIT Bhubaneswar by Team Arkz.

📚 Table of Contents

📸 Interactive System Tour & Screenshots

Standby: Point A & Point B Initial Standby Phase 1: High-Tech Telemetry & GPS Navigation
Standby State Primary Route Active
Only Point A (Origin) & Point B (Destination) pinned; path generated on click. Primary arterial mapped with real OpenRouteService waypoints & live carrier TRK-8821.
Phase 2: Natural Voice Hazard Transmission Phase 2: Live Roadblock & Autonomous Braking
Driver Voice NLP Webhook Modal Incident Blockade Detected
Drivers report accidents, wood blockages, or floods via conversational speech. Carrier halts automatically; Gemini dynamically classifies incident category & severity.

Phase 3: Autonomous Green Bypass Reroute & Stakeholder Notification Email
Autonomous Green Corridor Bypass    Autonomous Stakeholder Email Dispatch Log
LangGraph Strategist calculates the optimal green bypass and delivers urgent dispatch advisories with verified ETAs to client & warehouse inboxes.

🌟 Executive Summary

Global supply chains lose billions of dollars annually due to static routing engines that fail when unpredicted real-world disruptions strike. When a multi-vehicle highway accident occurs, storm debris drops fallen logs across an arterial corridor, or a sudden flood halts transport, legacy ERP systems wait hours for human dispatchers to intervene.

LogiPulse replaces static dispatching with an autonomous agentic command center:

  1. Initial Standby & On-Demand Path Generation: When loaded or when new points/presets are picked, the map shows only Point A and Point B. The route is computed dynamically only when the operator triggers Phase 1: Calculate Route.
  2. Dynamic Speech-to-NLP Incident Extraction: Field drivers speak naturally into their browser or mobile microphone (e.g. “Terrible accident near Maduravoyal on Chennai Port Corridor, container overturned across both lanes!”). Google Gemini classifies the exact category (ACCIDENT, FALLEN_TREE_WOOD, WATERLOGGING_FLOOD, PROTEST_STRIKE, ROAD_BLOCKAGE) and extracts location and severity with zero human delay.
  3. 100% Dynamic Orthogonal Detour Geometry: Rather than hardcoded pre-baked bypasses, LogiPulse derives orthogonal normal vectors $(-V_{\text{lon}}, V_{\text{lat}}) \times \text{ratio}$ around the dynamic incident point, querying OpenRouteService dynamically worldwide.
  4. LangGraph Strategist Reasoning: Evaluates crowdsourced hazard reports, real-time meteorological conditions (OpenWeatherMap), and actual highway topography (OpenRouteService).
  5. Cross-Sensor Telemetry Verification: Intelligently diagnoses localized infrastructure failures when flood reports conflict with 0.0mm radar precipitation.
  6. Automated Stakeholder Dispatch: The agent autonomously drafts and transmits formal emergency notifications to the warehouse manager and client with verified ETAs.

🗺️ Default Route & Regional Freight Corridors

The system defaults to high-volume coastal container freight and supports quick regional presets or full interactive coordinate placement anywhere on earth:

1. Default Freight Corridor (Tamil Nadu):

2. Odisha Regional Corridors (IIT Bhubaneswar):

3. Interactive Map Pin Placement:

🔄 Dynamic Standby Paradigm & On-Demand Route Generation

To give logistics managers complete operational control:

📐 Dynamic Orthogonal Bypass Mathematics

When an incident strikes at coordinate $H$ along route vector $\vec{V} = (\Delta \text{lat}, \Delta \text{lon})$, LogiPulse derives the perpendicular normal vector: \(\vec{N} = \left( -\Delta \text{lon}, \; \Delta \text{lat} \right)\)

The bypass waypoint is placed dynamically at: \(P_{\text{bypass}} = H + \vec{N} \times \delta\)

This intermediate waypoint is queried via OpenRouteService for real highway road geometry, with geodesic Haversine Bezier fallback if external networks are offline.

🏗️ End-to-End System Architecture

flowchart TD
    subgraph Field ["🌐 Field & Telemetry Layer"]
        Driver["📱 Truck Driver Mobile / Voice Webhook"]
        WeatherAPI["🌦️ OpenWeatherMap API (Live Temp/Rain)"]
        ORS_API["🗺️ OpenRouteService API (400+ GPS Waypoints)"]
    end

    subgraph Backend ["⚡ FastAPI Backend (Port 8010)"]
        Webhook["POST /api/report_hazard_voice"]
        HazardDB[("🧠 In-Memory Hazard Registry")]
        Orchestrator["POST /api/orchestrate"]
        
        subgraph AgenticEngine ["🤖 LangGraph Agentic Brain"]
            StrategistNode["Strategist Node (Gemini 2.5 Flash)"]
            Tools["Tool Executor Node"]
            
            T1["get_crowdsourced_traffic()"]
            T2["get_weather_disruptions()"]
            T3["get_map_routes()"]
            T4["notify_stakeholders()"]
        end
    end

    subgraph Frontend ["🖥️ Command Center UI (Port 5180)"]
        ThreeCanvas["🌌 React Three Fiber 3D Particle Constellation"]
        LeafletMap["🗺️ Leaflet Map (60fps Truck Tracking)"]
        TerminalFeed["💻 Agent Activity Terminal & Email Inspector"]
        AudioSFX["🔊 Pitch-Optimized Web Audio API Synthesizer"]
    end

    Driver -->|Voice Speech / Text| Webhook
    Webhook --> HazardDB
    HazardDB --> T1
    WeatherAPI --> T2
    ORS_API --> T3
    
    Orchestrator --> StrategistNode
    StrategistNode <--> Tools
    Tools --> T1 & T2 & T3 & T4
    
    T4 -->|Auto-Email| Stakeholders["📧 Warehouse & Client Inboxes"]
    
    Orchestrator -->|Live Telemetry| Frontend
    Frontend --> LeafletMap & TerminalFeed & ThreeCanvas & AudioSFX

🧪 Comprehensive Unit & Integration Test Suite

LogiPulse features 55 automated unit and integration tests passing with 100% success across the backend, LangGraph agent machine, and React frontend:

Test Layer Framework Test Count Pass Rate Scope Covered
Backend REST APIs pytest + httpx 10 100% Healthcheck, Weather API, Route Directions, Hazard Ingestion, Speech-to-NLP parsing
LangGraph Agent Engine pytest + langgraph 9 100% State persistence, Multi-tier corridor escalation (Tier 1 → 2 → 3 → 4), Cross-sensor flood conflict diagnosis
Logistics Tools pytest 7 100% Live weather radar fallback, ORS waypoint queries, stakeholder email dispatching
Frontend UI Components vitest + @testing-library/react 8 100% RouteStatsCard metrics, DisruptionBanner states, ControlPanel user interactions
Frontend API Client vitest + axios 8 100% Resilient fallback simulators, weather fetchers, voice webhook error handling
Geometry & Data Utilities vitest 8 100% Orthogonal bypass calculations, polyline coordinate interpolation, preset hubs
Audio Synthesizer vitest 5 100% Web Audio API oscillator lifecycles, volume ramping, toggle controls
TOTAL   55 Tests 100% Passed Zero failures, full regression safety

Running Backend Tests

# In project root:
.\venv\Scripts\pytest tests/ -v

Running Frontend Tests

# In frontend directory:
cd frontend
npm test

🚀 Quick Start Guide

Prerequisites

1. Clone & Configure .env

git clone https://github.com/Arkz-Deepak/agentic-supply-chain.git
cd agentic-supply-chain

Create a .env file in the project root:

GEMINI_API_KEY=your_google_gemini_api_key
MAP_API_KEY=your_openrouteservice_api_key
WEATHER_API_KEY=your_openweathermap_api_key

2. Launch the FastAPI Backend (Port 8010)

# In root directory:
.\venv\Scripts\python.exe -m uvicorn server:app --app-dir src --host 0.0.0.0 --port 8010 --reload

Backend runs at: http://localhost:8010
Interactive Swagger API documentation: http://localhost:8010/docs

3. Launch the Vite Frontend (Port 5180)

# In frontend directory:
cd frontend
npm install
npm run dev

Command Center runs at: http://localhost:5180

🔄 CI/CD Pipeline (GitHub Actions)

Every pull request and push to main or phase-1 is automatically validated through our GitHub Actions workflow (.github/workflows/ci.yml):

flowchart LR
    Push["Git Push / PR"] --> CI["GitHub Actions CI/CD"]
    CI --> Job1["🐍 Backend CI (Python 3.12)
• pip install -r requirements.txt
• pytest tests/ -v (26 tests)"]
    CI --> Job2["⚛️ Frontend CI (Node 20)
• npm install --legacy-peer-deps
• npm test (29 tests)
• npm run build"]
    Job1 --> Merge["✅ Green Build Pass"]
    Job2 --> Merge

🚀 Vercel Deployment Guide

LogiPulse is 100% optimized for Vercel deployment:

Monorepo Deployment on Vercel

The repository includes root vercel.json and an ASGI serverless handler in api/index.py.

  1. Import your GitHub repository into Vercel Dashboard.
  2. Set the Framework Preset to Vite.
  3. In Environment Variables, configure:
    • GEMINI_API_KEY: Your Google Gemini API Key
    • WEATHER_API_KEY: Your OpenWeatherMap Key
    • MAP_API_KEY: Your OpenRouteService Key
  4. Deploy! Vercel compiles static assets to frontend/dist and routes /api/* to the serverless ASGI function.

📡 API Reference

For detailed request/response schemas and curl examples, see docs/API.md.

Endpoint Method Description
/api/health GET Healthcheck and active system capabilities
/api/weather GET Live meteorological telemetry from OpenWeatherMap
/api/routes/directions POST Highway driving waypoints from OpenRouteService
/api/report_hazard POST Structured IoT or manual incident reporting
/api/report_hazard_voice POST Natural language driver speech-to-NLP (Gemini Flash)
/api/orchestrate POST Full LangGraph agent multi-sensor workflow
/api/hazards DELETE Clears in-memory active hazard reports

🎯 Hackathon Presentation Pitch Script

For the comprehensive demonstration script and anticipated judge defenses, see docs/PITCH_DEMO_GUIDE.md.

Stage Action on Screen Audio / Visual Result What to Say to the Judges
1. Standby Intro Open http://localhost:5180 Map frames Point A & Point B with floating standby callout. Zero premature paths. “Notice the clean standby state: only Origin Point A and Destination Point B are pinned. The system avoids drawing assumptions until the operator initiates the mission.”
2. Phase 1 Dispatch Click “Phase 1: Calculate Route” Mechanical click sounds. Real OpenRouteService polyline illuminates. Carrier TRK-8821 begins driving. Telemetry metrics activate. “In Phase 1, LogiPulse establishes the optimal commercial freight corridor between Chennai Port Container Terminal and Oragadam Industrial Corridor.”
3. Phase 2 Crisis Click “Phase 2: Speak Driver Report 🎙️” Dispatch alert tone sounds. Gemini dynamically classifies crisis. Red pulsing hazard appears. The truck physically brakes and halts. “Disaster strikes! The driver reports an incident in conversational speech. Gemini dynamically identifies the category (accident, wood blockage, or flood). The truck halts instantly.”
4. Agent Action Click “AUTONOMOUS AGENT REROUTE” Terminal stream logs Gemini evaluating crowdsourced telemetry, calculating orthogonal bypass, and dispatching stakeholder notices. “Instead of stalling for hours, our LangGraph agent evaluates live radar, computes the orthogonal green bypass, and drafts emergency stakeholder emails.”
5. Resolution Automatic transition Harmonic chime plays. Emerald bypass corridor illuminates. The truck pivots onto the green bypass and drives safely to destination. “The delivery is saved with only an +8 minute delta. The Email tab proves the formal dispatch notice was autonomously delivered to the warehouse manager.”

📖 Detailed Documentation Links

🛡️ License

This project is open-source under the MIT License. Built with pride by Team Arkz for Tech Zephyr 4.0 at IIT Bhubaneswar.