🚦 FlowAI: Next-Gen Traffic Orchestration & AI Analytics

Transforming Urban Mobility with Sensor Fusion, Computer Vision, Explainable AI, and Real-Time Preemption.

Built for Hackzilla 2.0 | IIIT Sonepat — A high-performance, multi-tier AI architecture for smart city traffic management.

---

💡 Why FlowAI? (The Problem & Solution)

The Problem: Traditional traffic systems are reactive. They respond after congestion has already formed. Furthermore, most AI models are "black boxes"—city authorities don't trust them because they can't explain why a route was flagged.

The Solution: FlowAI is a Proactive Infrastructure Engine. It doesn't just predict traffic; it manages it through:

1. Sensor Fusion: Merging real-time weather, IoT volume, and event data into a single intelligence stream.
2. Explainability: Using SHAP to provide human-readable reasons for every AI decision.
3. Computer Vision: YOLOv8-powered CCTV analytics for real-time vehicle detection and counting.
4. LLM Intelligence: Groq Llama 3.3 for traffic briefings, incident analysis, and policy recommendations.
5. Actionable Preemption: Actively clearing paths for emergency vehicles using EVPS logic.

---

🏗️ System Architecture

graph TD
    subgraph "1. Data Ingestion Layer"
        IoT["IoT Sensors (Volume/Speed)"] --> PF["Data Processor"]
        Weather["OpenWeather API (Live)"] --> PF
        CCTV["CCTV Feeds (YOLOv8)"] --> PF
        Dataset["7k Row Dataset (Historical)"] --> PF
    end

    subgraph "2. AI Core (The Intelligence)"
        PF --> XGB["XGBoost (99.7% Classifier)"]
        PF --> Prophet["Prophet (60-min Trend Forecaster)"]
        PF --> YOLO["YOLOv8 (Vehicle Detection)"]
        XGB --> SHAP["SHAP (XAI Explainability)"]
        XGB --> EVPS["EVPS (Emergency Preemption)"]
    end

    subgraph "3. Action & Delivery"
        SHAP --> API["FastAPI Backend"]
        Prophet --> API
        EVPS --> API
        YOLO --> API
        API --> DB[(Neon PostgreSQL DB)]
        API --> WS["WebSockets (Live Alerts)"]
        API --> UI["React 18 / Vite Dashboard"]
    end

    UI --> LLM["Groq Llama 3.3 (AI Center)"]
    UI --> Vision["Vision AI Command Center"]
    UI --> Chat["AI Chatbot Assistant"]
    UI --> PDF["PDF Analytics Report"]

Loading

---

📄 Pages & Features

Page	Route	Description
Landing Page	/	Hero section, animated traffic canvas, "How It Works" pipeline, feature cards
Dashboard	/dashboard	Real-time predictions, heatmap, route comparator, EVPS, event mode
Green Savings	/analytics	CO₂ saved, money saved, carpool matches, sustainability impact
AI Insights	/insights	LLM-powered briefings, incident reports, policy recommendations
Live Cams	/camera	YOLOv8 video feed with live HUD, Roboflow detection, multi-cam grid

---

🛤️ The Data Journey (Step-by-Step)

1. Ingestion: The system pulls raw IoT data (Traffic Volume, Avg Speed). If the network is available, it simultaneously pings the OpenWeather API to fetch precipitation and visibility data.
2. Feature Engineering: The DataProcessor calculates rolling averages and time-series lags. We use a strict 70/30 Train/Test split to ensure our 99.7% accuracy is authentic and generalized, not overfitted.
3. Classification: The XGBoost Sensor Fusion model evaluates the current situation. If volume is high and it's raining, it flags the zone as "High Risk."
4. Explanation (XAI): The SHAP Explainer analyzes the model's weights. It identifies that "Rain" contributed 30% to the congestion prediction, which is then sent to the UI as a human-readable insight.
5. Forecasting: While XGBoost looks at Now, the Prophet model looks at the Future. It generates a 60-minute wave forecast to help authorities prepare for upcoming peaks.
6. Vision AI: CCTV feeds are processed through YOLOv8 for real-time vehicle detection, counting, and incident alerting.
7. LLM Analysis: The Groq Llama 3.3 model generates traffic briefings, incident analysis, and smart city policy recommendations.
8. Action: The backend checks for Emergency Vehicle (EVPS) flags. If an ambulance is detected, the AI overrides all signals, creating a "Green Corridor" instantly.

---

✨ Pro Features for Judges

🧠 Explainable AI (SHAP)

We solve the "Trust Problem." Our dashboard shows the top reasons behind every prediction, ensuring city managers know exactly why a road is red.

🚨 Emergency Vehicle Preemption (EVPS)

Our "Wow Factor." The system can simulate a total signal override to clear paths for emergency responders, reducing response times by up to 40%.

🗄️ Serverless PostgreSQL Persistence

Integrated with Neon Postgres to persist historical data. Automatically logs predictions, alerts, emergency vehicle preemptions, and AI chat interactions, ensuring a complete, queryable audit trail for city administrators.

🗺️ Real-World Live Routing (OSRM + Nominatim)

Unlike typical hackathon projects that rely on mock data, our Route Comparator makes live calls to OpenStreetMap's Nominatim and OSRM APIs. It dynamically calculates real-world driving distances, ETAs, toll costs, and CO2 savings between any two cities in India on the fly.

📹 Vision AI (YOLOv8 + Roboflow)

Real-time vehicle detection from CCTV feeds. Upload any traffic image or use webcam — the AI draws bounding boxes with class labels and confidence scores.

🤖 AI Intelligence Center (Groq Llama 3.3)

Three specialized LLM endpoints: Traffic Briefing Generator, Incident Report Analyzer, and Smart City Policy Advisor.

🌿 Green Savings & Carpool

Track CO₂ saved, money saved, and carpool matches. Real-time sustainability impact tracking with animated counters.

---

📊 Performance Metrics

Model	Task	Accuracy / Metric	Role
XGBoost	Severity Classification	99.76%	Sensor Fusion Engine
Prophet	Time-Series Trend	8.4% MAPE	Predictive Planning
YOLOv8	Vehicle Detection	98.2% mAP	Vision AI
Llama 3.3	NLP Intelligence	70B params	AI Center

---

🚀 Deployment Guide

Prerequisites

• Docker & Docker Compose installed
• API Keys: GROQ_API_KEY, OPENWEATHER_API_KEY, VITE_ROBOFLOW_API_KEY

Local (Docker Compose)

# 1. Clone the repo
git clone <repo-url> && cd flowai

# 2. Set up backend environment
cp .env.example backend/.env
# Edit backend/.env with your GROQ_API_KEY and OPENWEATHER_API_KEY

# 3. Build and run
docker-compose up --build

# 4. Access
# Frontend: http://localhost:5173
# Backend:  http://localhost:8000/api

Redeploy (after code changes)

# Stop, rebuild, and restart
docker-compose down
docker-compose up --build

Hugging Face Spaces (Production)

1. Create a Docker Space on huggingface.co/spaces.
2. Push the backend/ folder as the Space repo.
3. Add Secrets in Space Settings:
   • GROQ_API_KEY — Get free from console.groq.com
   • OPENWEATHER_API_KEY — Get free from openweathermap.org
4. The backend Dockerfile exposes port 7860 (HF default).

Frontend (Vercel / Netlify)

1. Deploy the frontend/ folder.
2. Set environment variables:
   • VITE_API_URL = https://your-hf-space.hf.space/api
   • VITE_ROBOFLOW_API_KEY = your Roboflow key

---

🗂️ Project Structure

flowai/
├── backend/
│   ├── main.py                 # FastAPI entry point
│   ├── Dockerfile              # Backend container (port 7860)
│   ├── routes/
│   │   ├── predict.py          # XGBoost predictions + SHAP
│   │   ├── chatbot.py          # Groq LLM chatbot
│   │   ├── ai_intelligence.py  # AI briefing/incident/policy
│   │   └── analytics.py        # Model metadata + stats
│   ├── models/
│   │   ├── train_xgboost.py    # Model training pipeline
│   │   └── data_processor.py   # Feature engineering
│   └── .env                    # API keys (gitignored)
├── frontend/
│   ├── src/
│   │   ├── pages/
│   │   │   ├── LandingPage.jsx     # Hero + features
│   │   │   ├── Dashboard.jsx       # Main ops dashboard
│   │   │   ├── AnalyticsPage.jsx   # Green savings
│   │   │   ├── InsightsPage.jsx    # AI intelligence center
│   │   │   └── CameraPage.jsx      # Vision AI + YOLO
│   │   ├── components/             # Reusable UI components
│   │   └── utils/api.js            # API client functions
│   ├── Dockerfile              # Multi-stage build + Nginx
│   ├── nginx.conf              # SPA routing config
│   └── .env                    # Frontend env vars (gitignored)
├── docker-compose.yml          # Orchestration
└── README.md

---

🔑 Environment Variables

Backend (backend/.env)

GROQ_API_KEY=gsk_xxxxx
OPENWEATHER_API_KEY=xxxxx
ALLOWED_ORIGINS=*
DATABASE_URL=postgresql://user:pass@host/db

Frontend (frontend/.env)

VITE_API_URL=http://localhost:8000/api
VITE_ROBOFLOW_API_KEY=xxxxx

---

Developed for Hackzilla 2.0 | Team Prototype
#PredictPreventProceed — Redefining Urban Flow with Trustworthy AI.