• 

  Dashboard

RiverGuard AI

Real-Time Flood Risk Intelligence for Kerala

WeatherWise Hack 2026 · AI & Data Innovation Track

"In August 2018, Pathanamthitta district watched the Pamba river rise 7 metres above danger level in under 48 hours. 54 of Kerala's 61 dams opened their shutters simultaneously. Over 5.4 million people were displaced. We had no warning system that could tell a village — in plain language — that it was time to leave."

RiverGuard AI is built so that never happens again.

---

The Problem This Solves

Kerala 2018 — The Flood That Changed Everything

August 2018 brought the worst floods Kerala had seen in 100 years. The numbers tell part of the story:

• 483 people killed
• 5.4 million displaced from their homes
• 1,50,000+ houses damaged or destroyed
• ₹31,000 crore in economic damage
• 14 of 14 districts affected simultaneously
• Idukki reservoir hit 95% capacity — the first time in 26 years its shutters were opened

But the numbers don't capture what actually happened on the ground. The crisis wasn't just the rain — it was the information gap. Families in low-lying areas of Alappuzha, Kottayam, and Pathanamthitta didn't know whether to evacuate or wait. Dam shutter openings upstream gave downstream villages less than two hours to respond. Local officials had no centralized tool to see which districts were about to tip from medium to critical.

That gap — between weather data and human action — is exactly what RiverGuard AI closes.

Why Again in 2019, 2020, and 2021?

Kerala flooded significantly in every subsequent monsoon season. This is not a one-time anomaly. The Western Ghats receive 2,000–4,000mm of rainfall annually. Wayanad's steep slopes channel water into the lowland districts within hours. Alappuzha sits at sea level with no natural drainage outlet. Pathanamthitta's Pamba river basin drains the entire southern highlands through a single corridor.

The hydrology hasn't changed. What needs to change is the early warning infrastructure.

---

What RiverGuard AI Does

RiverGuard AI is a real-time flood risk intelligence platform that:

1. Fetches live weather data from Open-Meteo (real-time rainfall, soil moisture, 72-hour cumulative precipitation) for all 14 Kerala districts simultaneously
2. Runs an ML risk prediction using a trained Random Forest + XGBoost ensemble model that weighs 10 hydrological features to output a Low / Medium / High risk classification with confidence probability
3. Displays everything on an interactive SVG map of Kerala with animated district markers — HIGH risk zones pulse red in real time
4. Generates contextual alerts with specific recommended actions per district — not generic warnings, but district-specific guidance based on local geography
5. Answers questions via Gemini AI with full live data context — ask it "why is Alappuzha high risk?" and it explains based on actual current rainfall and river level data
6. Auto-refreshes every 5 minutes — the dashboard is always current without manual intervention

---

Coverage — All 14 Kerala Districts

Every district has individually calibrated parameters — elevation, slope, drainage density, urban fraction, distance to nearest river — reflecting its unique flood profile.

#	District	Key River	Primary Risk Factor
1	Thiruvananthapuram	Karamana, Neyyar	Coastal + urban runoff
2	Kollam	Kallada	Ashtamudi lake overflow
3	Pathanamthitta	Pamba, Achankovil	2018 epicentre, dam releases
4	Alappuzha	Pamba delta	0m elevation, backwater flooding
5	Kottayam	Meenachil, Manimala	Vembanad lake, low-lying terrain
6	Idukki	Periyar	High elevation, reservoir releases
7	Ernakulam	Periyar, Muvattupuzha	Dense urban, river confluence
8	Thrissur	Chalakudy, Bharathapuzha	Low-lying plains, flash floods
9	Palakkad	Bharathapuzha, Kalpathipuzha	Palakkad Gap wind-driven rain
10	Malappuram	Bharathapuzha, Chaliyar	Rapid urbanisation, poor drainage
11	Kozhikode	Chaliyar, Kadalundi	Hilly terrain, landslide risk
12	Wayanad	Kabani, Mananthavady	Western Ghats, steepest slopes
13	Kannur	Valapattanam, Kuppam	Coastal + riverine combined
14	Kasaragod	Chandragiri, Payaswini	Northernmost, laterite soil

---

ML Model — How the Prediction Works

The risk engine is a Random Forest (200 trees) + XGBoost (150 estimators) ensemble, blended 55/45. It was trained on 8,000 physics-informed synthetic samples modelled after real Kerala flood records from 2018, 2019, and 2020.

The 10 Features

Feature	Weight	Why It Matters
Rainfall last 24h	29.8%	Immediate flood trigger — above 64mm/day is danger threshold
Rainfall last 72h	28.8%	Cumulative storm loading saturates soil and fills rivers
River level ratio	25.4%	How close the river is to its bank-full capacity
Soil saturation	5.2%	Saturated soil cannot absorb — all rain becomes runoff
Elevation	2.6%	Low-lying districts face inundation risk at lower rainfall volumes
Drainage density	2.2%	Fewer channels = slower discharge = more flooding
Antecedent rain (7 days)	2.0%	Prior week's rain determines how much soil can still absorb
Distance to river	1.8%	Flood zone proximity — Alappuzha's 50m vs Idukki's 300m
Urban fraction	1.3%	Concrete surfaces increase runoff coefficient
Slope	0.9%	Steep slopes accelerate water movement to lowlands

Output

Each prediction returns:

• Risk class: Low / Medium / High
• Confidence score: e.g. 84% High
• Probability distribution: across all three classes
• Recommended actions: district-specific, severity-calibrated guidance
• Top risk drivers: which features pushed this prediction

---

File Structure

riverguard-ai/
│
├── index.html              ← Complete frontend — open this in a browser
│                             Fully standalone, no server or install needed
│
├── backend.py              ← FastAPI backend (optional)
│                             Server-side ML predictions + multi-API weather
│
├── requirements.txt        ← Python dependencies for backend
│
├── README.md               ← You are here
│
└── model/
    ├── train.py            ← ML training script (run once)
    └── artifacts/          ← Pre-trained models, ready to use
        ├── rf_model.pkl
        ├── gb_model.pkl
        ├── scaler.pkl
        ├── feature_importance.json
        └── features.json

---

Tech Stack

Layer	Technology	Notes
Frontend	HTML / CSS / JS	Zero build step — opens directly in browser
Map	Custom SVG	All 14 Kerala districts, pixel-accurate layout
Charts	Chart.js + D3.js	Rainfall bars, 7-day trends, feature importance
Weather	Open-Meteo API	Free, no key required, real-time data
ML	Random Forest + XGBoost	88% accuracy, 10 hydrological features
Backend	FastAPI (Python)	Async, lightweight, auto-generates API docs
AI Chat	Google Gemini 2.0 Flash	Free tier, live flood data injected as context
Alerts	Rule-based engine	Threshold-driven, district-specific

---

Backend API Reference

When running backend.py:

Method	Endpoint	Description
GET	/	System status and model info
GET	/locations	All 14 district coordinates and parameters
GET	/predict/{district_id}	Risk prediction for one district
GET	/dashboard	All 14 districts predicted in parallel
GET	/alerts	Current active alert feed
GET	/historical/{id}?days=7	7-day risk trend history
POST	/predict/manual	Prediction for any custom coordinates
POST	/alerts/sms	Trigger Twilio SMS alert (optional)

---

What Makes This Different

Most flood warning systems show you a weather forecast. RiverGuard AI shows you a risk verdict.

Not "it will rain 60mm tomorrow" — but "Alappuzha is at HIGH risk. Residents of low-lying wards should begin evacuation now."

That distinction matters because:

• A family in Kuttanad doesn't need to understand millibars. They need to know whether to move tonight.
• A district collector managing 14 zones needs a single screen, not 14 weather apps.
• A rescue coordinator needs to know which district tips to HIGH first — not which got the most rain.

The ML model does the translation from raw data to human decision. The Gemini assistant handles follow-up questions with full live context. The map shows everything at a glance.

---

Built for WeatherWise Hack 2026 — AI & Data Innovation Track Smarter Weather. Safer World.

Built With

• ai
• css
• fastapi
• html
• javascript
• ml
• python