🏔️ HILLGUARD

AI + IoT + GIS Powered Multi-Hazard Early Warning System

Sense → Fuse → Predict → Alert → Respond → Learn

A full-stack disaster intelligence and decision-support platform for vulnerable hilly and mountainous regions.

---

📌 Table of Contents

• Overview
• Problem Statement
• Core Workflow
• Key Capabilities
• System Architecture
• Technology Stack
• Application Modules
• Project Structure
• Risk Intelligence
• AI Emergency Assistant
• Security Architecture
• REST API
• Local Development
• Optional Python Tools
• Testing
• Deployment
• Production Security Checklist
• Development Workflow
• Roadmap
• Engineering Philosophy
• Documentation
• License
• Disclaimer

---

🌍 Overview

HillGuard is an AI-powered, IoT-enabled, GIS-based disaster intelligence platform designed for rapidly developing hazards in hilly and mountainous environments.

The platform brings multiple information streams into a unified Disaster Command Center:

• 📡 Environmental and IoT telemetry
• 🌦️ Weather information
• 📊 Risk and prediction analysis
• 🗺️ GIS-based hazard visualization
• 📚 Historical disaster intelligence
• 🚨 Alert and escalation workflows
• 🏥 Emergency-response coordination
• 🤖 AI-assisted disaster reasoning and decision support

The core idea is simple:

Turn distributed environmental information into localized, understandable, and operationally useful disaster intelligence.

HillGuard is designed as a human-in-the-loop system. Automated predictions and AI outputs support operational teams; they do not replace official warnings, trained emergency personnel, or established emergency procedures.

---

🎯 Problem Statement

Hilly and mountainous regions can be exposed to fast-changing hazards such as:

Hazard	Example Signals
🌊 Flash Floods	Heavy rainfall, rising water levels
⛰️ Landslides	Soil saturation, slope instability
🌧️ Cloudbursts	Extreme short-duration rainfall
🌊 River Surges	Rapid river/water-level increase
🌱 Ground Instability	Soil moisture and terrain-related indicators

Traditional monitoring can become difficult when information is distributed across different data sources and operational teams.

HillGuard's approach

          MULTI-SOURCE INFORMATION
                    │
        ┌───────────┼───────────┐
        ▼           ▼           ▼
      IoT        Weather     Historical
     Sensors       Data        Data
        └───────────┼───────────┘
                    ▼
              DATA FUSION
                    ▼
            RISK INTELLIGENCE
                    ▼
       ┌────────────┼────────────┐
       ▼            ▼            ▼
      Flood     Landslide     Overall
      Risk        Risk         Risk
       └────────────┼────────────┘
                    ▼
             ALERT / ESCALATE
                    ▼
       DASHBOARD + GIS + RESPONSE
                    ▼
             HUMAN DECISION

---

🔄 Core Workflow

HillGuard follows an operational pipeline:

┌─────────┐
│  SENSE  │  Collect environmental information
└────┬────┘
     ▼
┌─────────┐
│  FUSE   │  Combine telemetry + weather + history
└────┬────┘
     ▼
┌──────────┐
│ PREDICT  │  Estimate multi-hazard risk
└────┬─────┘
     ▼
┌─────────┐
│  ALERT  │  Generate risk-aware warnings
└────┬────┘
     ▼
┌─────────┐
│ RESPOND │  Coordinate emergency resources
└────┬────┘
     ▼
┌────────┐
│  LEARN │  Review incidents and improve models
└────────┘

---

🚀 Key Capabilities

1. 📡 Real-Time IoT Telemetry

HillGuard provides centralized visibility into distributed environmental monitoring stations.

Supported measurements

• 🌧️ Rainfall
• 🌊 River / water level
• 🌱 Soil moisture
• ⛰️ Slope stability
• 🌡️ Temperature
• 📍 Station and location information
• 🟢 Sensor health and connectivity

The dashboard can display station state and telemetry trends so operators can monitor environmental changes from one place.

---

2. 🤖 AI-Powered Risk Prediction

HillGuard combines environmental indicators to produce separate risk dimensions.

Risk inputs

Rainfall ───────────────┐
                        ├──► Flood Risk
Water Level ────────────┘

Soil Moisture ──────────┐
                        ├──► Landslide Risk
Slope Stability ────────┘

Historical Risk ───────────► Overall Risk Intelligence

Risk outputs

• Overall risk
• Flood risk
• Landslide risk
• Risk trend
• Lead-time estimate
• Model version
• Prediction inputs
• Confidence / uncertainty information where available

⚠️ Risk predictions are decision-support outputs. They should be validated against official monitoring and emergency-management procedures before real-world action.

---

3. 🗺️ Interactive GIS Risk Map

The GIS module provides a geographic view of hazard intelligence and response resources.

Map layers

• 🌊 Flood-risk areas
• ⛰️ Landslide-risk areas
• 📡 IoT monitoring stations
• 👥 Population / vulnerable communities
• 🏥 Emergency shelters
• 🚨 Active alerts
• 📍 Monitored locations

GIS technologies

• Leaflet
• React-Leaflet
• OpenStreetMap-compatible map tiles

The map is intended to help operators understand the spatial relationship between hazards, monitoring stations, exposed communities, and emergency resources.

---

4. 🚨 Intelligent Alert Management

HillGuard provides centralized warning and alert workflows.

Severity model

LOW
  ↓
MODERATE
  ↓
HIGH
  ↓
CRITICAL

Alert data

Field	Description
Hazard	Flood, landslide, etc.
Severity	Current alert level
Location	Affected area
Message	Operator-facing warning
Timestamp	Alert creation time
Expiration	Alert validity
Status	Active / inactive
Response	Current response state

Response concepts

• SOS broadcasts
• Alert escalation
• Operator acknowledgement
• Targeted notifications
• Emergency-response workflows

---

5. 📊 Live Monitoring Dashboard

The command dashboard consolidates operational indicators into one interface.

Dashboard indicators

• Overall risk
• Flood risk
• Landslide risk
• Active alerts
• Sensor status
• Weather conditions
• Telemetry trends
• Monitored locations
• Emergency-response information

Dashboard data can be refreshed periodically to provide updated operational visibility.

---

6. 🧪 AI Simulation Lab

The Simulation Lab supports controlled what-if analysis.

Example scenario

Rainfall ↑
    +
Soil Saturation ↑
    +
River Level ↑
    │
    ▼
Potential Hazard Risk ↑

Simulation capabilities

• Flood scenarios
• Landslide scenarios
• What-if analysis
• Risk comparison
• Model-input inspection
• Prediction-output inspection
• Historical comparison
• Model-performance information

This allows users to study how changes in environmental inputs can affect calculated risk.

---

7. 📈 Historical Disaster Intelligence

Historical data supports analysis, comparison, and post-incident review.

Analytics

• Incident timeline
• Disaster type
• Location
• Severity
• Historical patterns
• Seasonal trends
• Risk comparison
• Post-incident analysis

Reporting concepts

• CSV export
• PDF reports
• Incident summaries
• After-action analysis

---

8. 🏥 Emergency Hub

The Emergency Hub connects risk intelligence with response coordination.

Response resources

• 🏠 Shelter availability
• 👥 Shelter capacity
• 🚑 Responder information
• 📦 Resource allocation
• 📞 Emergency contacts
• 🛣️ Evacuation planning
• 📄 Situation Report generation
• 📢 Community communication

---

🤖 AI Emergency Assistant

HillGuard includes an AI-assisted disaster intelligence interface.

Rather than sending a request directly to a single generation step, the emergency workflow uses a controlled multi-stage pipeline:

User Request
     │
     ▼
┌───────────────┐
│    Planner    │
└───────┬───────┘
        ▼
┌──────────────────┐
│  Safety Auditor  │
└────────┬─────────┘
         ▼
┌───────────────┐
│     Writer    │
└───────┬───────┘
        ▼
┌────────────────┐
│    Reviewer    │
└────────┬───────┘
         ▼
   Final Response

AI-supported functions

• Disaster-risk explanations
• Emergency scenario analysis
• Project knowledge
• Learning modules
• Incident reasoning
• Situation-report generation
• Emergency-response guidance

🧠 The AI assistant is intended as decision support, not as a replacement for emergency authorities or official warnings.

---

🔐 Authentication & Security

HillGuard includes application-security controls across authentication, authorization, API protection, and account recovery.

Authentication controls

• JWT authentication
• Password hashing with bcrypt
• Protected routes
• Role-based access control
• Session expiration
• Login / logout handling
• Password reset workflow
• Password recovery

Password reset architecture

Forgot Password
      │
      ▼
Secure Random Token
      │
      ▼
SHA-256 Token Hash
      │
      ▼
Database
      │
      ▼
Expiring Reset Link
      │
      ▼
Password Reset
      │
      ▼
Token Invalidated

Application security

• Helmet security headers
• CORS configuration
• Express rate limiting
• Input validation
• MongoDB / Mongoose validation
• Protected API routes
• Environment-variable configuration
• Request logging

---

👥 Role-Based Access Control

HillGuard supports role-oriented access.

Role	Example Responsibilities
👑 Admin	User management, configuration, administration
🏢 Authority	Risk monitoring, alerts, incident coordination
🚑 Responder	Emergency response, resource coordination
🧑‍💻 Operator	Monitoring and operational workflows
👤 Citizen	Public-facing information where enabled

Authorization is enforced on protected application routes and backend APIs.

---

🏗️ System Architecture

flowchart TD
    A[IoT Sensors] --> D[Data Fusion / API Layer]
    B[Weather Data] --> D
    C[Historical Data] --> D
    U[User Input] --> D

    D --> R[Risk & Prediction Engine]

    R --> F[Flood Risk]
    R --> L[Landslide Risk]
    R --> O[Overall Risk]

    F --> X[Alert / Escalation]
    L --> X
    O --> X

    X --> DB[Command Dashboard]
    X --> GIS[GIS Risk Map]
    X --> EH[Emergency Hub]

    DB --> HD[Human Decision]
    GIS --> HD
    EH --> HD

Loading

---

🧰 Technology Stack

Frontend

Technology	Purpose
React 19	User interface
React Router v7	SPA routing
Vite	Development and build tooling
Axios	API communication
Leaflet	Interactive maps
React-Leaflet	React GIS integration
Chart.js	Data visualization
Lucide React	Icons
Motion	UI animations
CSS3	Styling and responsive design

Backend

Technology	Purpose
Node.js	Runtime
Express.js 5	REST API
MongoDB	Database
Mongoose 9	ODM
JWT	Authentication
bcryptjs	Password hashing
Helmet	Security headers
CORS	Cross-origin control
Morgan	HTTP logging
Express Rate Limit	API protection

AI / Data Tooling

• Google Gemini / GenAI integration
• Python emergency tools
• NASA GPM IMERG precipitation data tooling
• MongoDB-backed AI memory
• Risk-calculation engine
• Historical disaster dataset

---

📁 Project Structure

HillGuard/
│
├── frontend/
│   ├── public/
│   │   └── assets/
│   ├── src/
│   │   ├── components/
│   │   ├── context/
│   │   ├── pages/
│   │   ├── services/
│   │   ├── styles/
│   │   ├── utils/
│   │   ├── App.jsx
│   │   ├── main.jsx
│   │   └── index.css
│   ├── index.html
│   ├── package.json
│   └── vite.config.js
│
├── backend/
│   ├── config/
│   ├── controllers/
│   ├── middleware/
│   ├── models/
│   ├── routes/
│   ├── scripts/
│   ├── services/
│   ├── utils/
│   ├── server.js
│   └── package.json
│
├── my_project/
│   ├── chat_terminal.py
│   ├── chat_api.py
│   ├── download_files_GPM_3IMERGDF_07.py
│   ├── requirements.txt
│   └── .env.example
│
├── OPERATOR_MANUAL.md
├── README.md
└── LICENSE

---

🧭 Application Modules

Module	Route	Purpose
🏠 Home	/	Project overview
🔐 Login	/login	Authentication
🔑 Forgot Password	/forgot-password	Account recovery
🔄 Reset Password	/reset-password	Password reset
📊 Dashboard	/dashboard	Command center
📡 Live Monitoring	/dashboard/monitoring	IoT telemetry
🗺️ Risk Map	/dashboard/risk-map	GIS risk visualization
🚨 Alerts	/dashboard/alerts	Warning management
🧪 Simulation Lab	/dashboard/simulation	What-if analysis
📈 Historical Data	/dashboard/history	Disaster archive
🏥 Emergency Hub	/dashboard/emergency-hub	Response coordination
🤖 AI Assistant	/dashboard/ai-assistant	AI intelligence
⚙️ Mission Control	/dashboard/admin	Administration

---

📊 Risk Intelligence

HillGuard uses a normalized 0–100 risk score for its displayed classification.

Score	Classification
0–29	🟢 Low
30–54	🟡 Moderate
55–74	🟠 High
75–100	🔴 Critical

The system can expose:

• Flood risk
• Landslide risk
• Overall risk
• Risk trends
• Prediction inputs
• Model version
• Lead-time estimate
• Confidence / uncertainty information where available

Important: The scoring and classifications are application decision-support outputs. Real-world emergency action must follow official monitoring, trained personnel, and established protocols.

---

🔌 REST API

Authentication

POST /api/auth/register
POST /api/auth/login
GET  /api/auth/me
POST /api/auth/forgot-password
POST /api/auth/reset-password/:token

Sensors

GET    /api/sensors
GET    /api/sensors/:id
POST   /api/sensors
POST   /api/sensors/:id/data
DELETE /api/sensors/:id

Risk & Prediction

GET  /api/risk
POST /api/risk/predict
GET  /api/predictions
POST /api/risk/historical

Alerts

GET  /api/alerts
POST /api/alerts
GET  /api/alerts/:id
PUT  /api/alerts/:id

Weather

GET /api/weather
GET /api/weather/forecast

AI

POST   /api/ai/chat
GET    /api/ai/session
PATCH  /api/ai/session
DELETE /api/ai/session
POST   /api/ai/emergency
GET    /api/ai/study-modules
GET    /api/ai/project-context

---

💻 Local Development

Prerequisites

Install:

• Node.js 18+
• npm 9+
• MongoDB 6+
• Git
• Python 3.11+ for optional Python tooling

---

1. Clone the Repository

git clone https://github.com/ROHIT3470/Disaster-Management.git
cd Disaster-Management

---

2. Configure the Backend

cd backend
npm install

Create:

backend/.env

Example:

PORT=5000

MONGO_URI=mongodb://127.0.0.1.............

JWT_SECRET=replace-with-a-long-random-secret
JWT_EXPIRES_IN=7d

CLIENT_URL=http://localhost:5173

NODE_ENV=development

SMTP_HOST=smtp.gmail.com
SMTP_PORT=465
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-gmail-app-password
SMTP_FROM=HillGuard <your-email@gmail.com>

Start the backend:

npm run dev

Backend:

http://localhost:5000

Health endpoint:

http://localhost:5000/api/health

---

3. Configure the Frontend

Open another terminal:

cd frontend
npm install

Create:

frontend/.env

Example:

VITE_API_URL=http://localhost:5000/api

Start the frontend:

npm run dev

Frontend:

http://localhost:5173

---

4. Seed Development Data

From the backend directory:

npm run seed

⚠️ The current seed workflow clears existing application collections before inserting demo data. Do not run it against a production database containing important data.

---

🧪 Testing

Backend

cd backend
npm test

Frontend build

cd frontend
npm run build

Preview production build

npm run preview

---

🐍 Optional Python Tools

Additional Python utilities are provided under:

my_project/

Install dependencies:

cd my_project
python -m pip install -r requirements.txt

Configure environment variables locally:

GEMINI_API_KEY=your-key
MONGO_URI=your-mongodb-uri

Example GPM downloader

python download_files_GPM_3IMERGDF_07.py \
  --start 2025-08-31T00:00:00.000Z \
  --end 2025-09-30T23:59:59.000Z \
  --bbox 91.55,25.95,91.9,26.3 \
  --output-dir ./GPM_3IMERGDF_07 \
  --workers 5

---

📈 Performance Targets

The platform is designed around the following engineering targets:

Metric	Target
API response	<100 ms for typical cached/simple requests
Database query	<50 ms for indexed operations
Alert processing	Near-real-time
Dashboard refresh	~30 seconds
Frontend bundle	Optimized through code splitting
Availability	Dependent on production infrastructure

Actual performance depends on infrastructure, database configuration, network conditions, traffic, and external APIs.

---

☁️ Deployment

Frontend

The Vite frontend can be deployed to:

• Vercel
• Netlify
• Static hosting / CDN

Build:

cd frontend
npm run build

Output:

frontend/dist/

Production API configuration:

VITE_API_URL=https://your-backend-domain/api

---

Backend

The Express backend requires a Node.js-compatible hosting provider.

Production environment example:

NODE_ENV=production

PORT=5000

MONGO_URI=mongodb+srv://...

JWT_SECRET=strong-random-production-secret
JWT_EXPIRES_IN=7d

CLIENT_URL=https://your-frontend-domain

SMTP_HOST=...
SMTP_PORT=...
SMTP_USER=...
SMTP_PASSWORD=...
SMTP_FROM=...

---

🍃 MongoDB Atlas

For production deployment:

1. Create a MongoDB Atlas cluster.
2. Create a database user.
3. Configure network access.
4. Create the database connection string.
5. Set the connection string in MONGO_URI.

Example:

MONGO_URI=mongodb+srv://USERNAME:PASSWORD@CLUSTER.mongodb.net/disaster_management

Never expose database credentials in frontend code.

---

🔒 Production Security Checklist

Before exposing HillGuard publicly:

[ ] Remove or disable demo credentials
[ ] Generate a strong random JWT_SECRET
[ ] Configure MongoDB Atlas securely
[ ] Restrict CORS origins
[ ] Enforce HTTPS
[ ] Configure SMTP securely
[ ] Never commit .env files
[ ] Rotate any exposed credentials
[ ] Enable production rate limiting
[ ] Validate API inputs
[ ] Review authorization on every protected endpoint
[ ] Disable development reset-link responses
[ ] Configure secure logging
[ ] Review MongoDB indexes
[ ] Test password recovery
[ ] Test expired JWT handling
[ ] Test unauthorized API access
[ ] Test admin authorization

Never commit secrets

Keep credentials in local environment files or your hosting provider's secret/environment-variable manager:

.env
.env.local
.env.production

Use .env.example files only for safe placeholders.

---

🛡️ Security Architecture

Authentication flow

User
  │
  ▼
Login
  │
  ▼
Credentials
  │
  ▼
bcrypt Verification
  │
  ▼
JWT Issued
  │
  ▼
Protected API

Password recovery flow

Forgot Password
      │
      ▼
Random Token
      │
      ▼
SHA-256 Hash
      │
      ▼
Database
      │
      ▼
Expiring Reset Link
      │
      ▼
Password Reset
      │
      ▼
Token Invalidated

Future security enhancements

• Refresh-token rotation
• HttpOnly secure cookies
• CSRF protection where cookie authentication is used
• MFA
• Audit-log integrity controls
• Security event monitoring
• Strong password policy
• Account lockout / risk-based authentication
• API schema validation
• Automated dependency scanning
• SAST / DAST in CI/CD

---

🔄 Development Workflow

Recommended Git workflow:

git checkout -b feature/<feature-name>

git add .

git commit -m "feat: add <feature>"

git push origin feature/<feature-name>

Then open a Pull Request.

Commit conventions

Prefix	Usage
feat:	New functionality
fix:	Bug correction
refactor:	Code restructuring
docs:	Documentation
style:	UI / formatting
test:	Tests
security:	Security improvement
perf:	Performance improvement

---

🧭 Roadmap

Phase 1 — Platform Hardening

• Production authentication architecture
• Advanced RBAC
• Audit logging
• API validation
• Automated testing
• CI/CD security checks

Phase 2 — Intelligence

• Improved ML models
• Model evaluation pipeline
• Feature-importance visualization
• Prediction-confidence calibration
• Model-version registry
• Continuous model monitoring

Phase 3 — IoT

• MQTT integration
• Device authentication
• Sensor heartbeat monitoring
• Offline sensor detection
• Telemetry anomaly detection
• Real-time streaming

Phase 4 — GIS

• Advanced hazard polygons
• Evacuation-route analysis
• Shelter proximity analysis
• Population exposure estimation
• Terrain / elevation integration
• Satellite-data integration

Phase 5 — Emergency Operations

• Multi-agency coordination
• Resource tracking
• Incident-command workflows
• Automated SITREP generation
• Notification-provider integration
• Offline emergency mode

---

🧠 Engineering Philosophy

HillGuard is built around a human-in-the-loop disaster intelligence model.

SENSE
  ↓
Collect environmental information

FUSE
  ↓
Combine telemetry + weather + historical context

PREDICT
  ↓
Estimate hazard risk

ALERT
  ↓
Generate actionable warnings

RESPOND
  ↓
Coordinate emergency resources

LEARN
  ↓
Analyze historical incidents and improve models

Design principles

Operational clarity
Present complex environmental information in a form that operators can interpret quickly.

Multi-source intelligence
Combine telemetry, weather, historical data, and geospatial context rather than relying on one signal.

Security by design
Treat authentication, authorization, secret management, input validation, and API protection as first-class concerns.

Human oversight
Use automation to support decisions, while keeping final operational authority with responsible human teams.

---

📚 Documentation

Additional project documentation includes:

• OPERATOR_MANUAL.md
• ARCHITECTURE.md
• SETUP.md
• DEPLOYMENT.md
• PROJECT_SUMMARY.md
• BUILD_VERIFICATION.md
• COMPLETION_CHECKLIST.md
• HillGuard_Official_4_Page_Summary.md

---

📄 Project Information

Field	Details
Project	HillGuard
Category	Disaster Management / Software
Focus	Flash Flood & Landslide Early Warning
Architecture	MERN + AI + IoT + GIS
Development Model	Full-stack web application
Repository	ROHIT3470/Disaster-Management

---

📜 License

This project is licensed under the MIT License.

See LICENSE for details.

---

⚠️ Disclaimer

HillGuard is a software research/development project intended for disaster-management intelligence, simulation, education, and decision-support purposes.

Risk predictions, simulations, alerts, and AI-generated recommendations must not be treated as a substitute for:

• Official government warnings
• Trained emergency personnel
• Hydrological / geotechnical assessments
• Established emergency-response protocols

For real-world emergencies, follow instructions from the relevant official emergency-management authorities.

---

🏔️ HILLGUARD

Sense → Fuse → Predict → Alert → Respond → Learn

Technology for faster disaster intelligence and better-informed emergency coordination.

Built for disaster resilience.

⭐ Star the repository if you find the project useful.