🛡️ Kavach - Disaster Alert & Risk Assessment System

Kavach (Sanskrit: कवच, meaning "Shield" or "Armor") is an intelligent disaster risk assessment and alert system that helps communities prepare for and respond to natural disasters including floods, landslides, and extreme weather events.

---

📋 Table of Contents

• Overview
• Features
• Tech Stack
• Architecture
• Getting Started
• Usage
• API Documentation
• Troubleshooting
• Project Structure
• Contributing
• License

---

🌟 Overview

Kavach is a comprehensive disaster management platform that combines:

• Real-time Risk Assessment using Machine Learning models
• Interactive Mapping with live disaster visualization
• Smart Alert System with email and SMS notifications
• AI-Powered Insights using Google Gemini for disaster guidance
• News Aggregation for real-time disaster updates
• Safe Zone Identification and evacuation planning

🎯 Problem Statement

Natural disasters cause significant loss of life and property. Early warning systems can save lives, but many communities lack access to sophisticated prediction and alert mechanisms. Kavach bridges this gap by providing:

• Accessible risk assessment for landslides and floods
• Personalized alert thresholds
• Real-time weather data integration
• AI-powered disaster preparedness guidance

---

✨ Features

🗺️ Interactive Risk Map

• Real-time visualization of disaster-prone areas
• Heat map overlays for landslide and flood risks
• Live weather data integration
• Location-based risk assessment

🤖 ML-Powered Risk Prediction

• Landslide Risk Classifier: Random Forest model trained on terrain, rainfall, and soil data
• Flood Risk Regressor: Predicts flood depth based on rainfall intensity, duration, and drainage
• Live weather API integration for current conditions
• Customizable simulation parameters

🚨 Smart Alert System

• Customizable alert thresholds for different disaster types
• Multi-channel notifications (Email + SMS)
• Email alerts via Resend API (cloud-compatible)
• SMS alerts via Twilio API
• Alert history tracking
• Real-time testing with loading indicators

🧠 AI Disaster Assistant

• Google Gemini-powered chatbot
• Context-aware disaster guidance
• Evacuation planning assistance
• Real-time disaster news integration
• Emergency contact information

📰 Live News Feed

• GNews API integration for disaster updates
• Filtered by disaster keywords and location
• Real-time alerts and emergency notifications

🏥 Safe Zones & Resources

• Emergency shelter locations
• Hospital and medical facility finder
• Police station and emergency services
• Community support centers

👤 User Management

• Firebase Authentication (Email/Password)
• Secure user profiles
• Persistent alert settings across devices
• Cloud-based data synchronization

---

🛠️ Tech Stack

Frontend

• React 18 - UI framework
• Vite - Build tool and dev server
• Leaflet - Interactive mapping
• Chart.js - Data visualization
• Lucide React - Icon library
• Firebase SDK - Authentication & Firestore

Backend

• FastAPI - Python web framework
• Python 3.13 - Programming language
• scikit-learn - Machine learning models
• NumPy - Numerical computations
• joblib - Model serialization

APIs & Services

• Google Gemini AI - Conversational AI
• Resend - Email delivery service
• Twilio - SMS notifications
• Open-Meteo - Weather data
• GNews API - News aggregation
• Firebase - Authentication & Firestore database

Development Tools

• Git & GitHub - Version control
• VS Code - Code editor
• Postman - API testing

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                    KAVACH SYSTEM                        │
└─────────────────────────────────────────────────────────┘

┌──────────────────┐         ┌──────────────────┐
│   FRONTEND       │         │   BACKEND API    │
│   (React + Vite) │ ◄────►  │   (FastAPI)      │
│                  │         │                  │
│  - Dashboard     │         │  - ML Models     │
│  - Risk Map      │         │  - Simulations   │
│  - Alerts UI     │         │  - Alert Logic   │
│  - AI Chat       │         │  - Weather API   │
└────────┬─────────┘         └────────┬─────────┘
         │                            │
         ▼                            ▼
┌──────────────────┐         ┌──────────────────┐
│   FIREBASE       │         │   EXTERNAL APIs  │
│                  │         │                  │
│  - Auth          │         │  - Gemini AI     │
│  - Firestore     │         │  - Resend Email  │
│  - Hosting       │         │  - Twilio SMS    │
└──────────────────┘         │  - Open-Meteo    │
                             │  - GNews API     │
                             └──────────────────┘

---

🚀 Getting Started

Prerequisites

• Node.js 18+ and npm
• Python 3.10+
• Git
• Firebase Account (free tier)
• API Keys for:
  • Google Gemini AI
  • Resend (email)
  • Twilio (SMS, optional)
  • GNews API

Installation

1. Clone the Repository

git clone https://github.com/yourusername/kavach.git
cd kavach

2. Backend Setup

# Navigate to backend directory
cd backend

# Create virtual environment
python -m venv myenv

# Activate virtual environment
# Windows:
myenv\Scripts\activate
# macOS/Linux:
source myenv/bin/activate

# Install dependencies
pip install -r requirements.txt

3. Frontend Setup

# Navigate to frontend directory
cd ../frontend

# Install dependencies
npm install

Configuration

Backend .env File

Create backend/.env:

# Gemini AI API Key
GEMINI_API_KEY=your_gemini_api_key_here

# GNews API Key
GNEWS_API_KEY=your_gnews_api_key_here

# Email Configuration (Resend)
RESEND_API_KEY=your_resend_api_key_here
SENDER_EMAIL=your_email@example.com

# SMS Configuration (Twilio - Optional)
TWILIO_ACCOUNT_SID=your_twilio_account_sid
TWILIO_AUTH_TOKEN=your_twilio_auth_token
TWILIO_PHONE_NUMBER=+1234567890

How to Get API Keys:

1. Gemini AI: https://makersuite.google.com/app/apikey
2. GNews: https://gnews.io/
3. Resend: https://resend.com/api-keys
4. Twilio: https://www.twilio.com/console

Frontend .env File

Create frontend/.env:

# Firebase Configuration
VITE_FIREBASE_API_KEY=your_firebase_api_key
VITE_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your-project-id
VITE_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=123456789
VITE_FIREBASE_APP_ID=1:123456789:web:abcdef
VITE_FIREBASE_MEASUREMENT_ID=G-ABCDEFG

# Backend API URL
VITE_API_URL=http://localhost:8000

Firebase Setup:

1. Go to https://console.firebase.google.com/
2. Create a new project
3. Enable Authentication (Email/Password)
4. Create a Firestore Database
5. Copy configuration from Project Settings

---

💻 Usage

Running Locally

1. Start Backend Server

cd backend
myenv\Scripts\activate  # Windows
# source myenv/bin/activate  # macOS/Linux

uvicorn main:app --reload

Backend will run at: http://localhost:8000

2. Start Frontend Development Server

cd frontend
npm run dev

Frontend will run at: http://localhost:5173

3. Access the Application

Open your browser and navigate to http://localhost:5173

First Time Setup

1. Create Account: Click "Sign Up" and register
2. Configure Alerts:
   • Click the bell icon (Alert Settings)
   • Enter your email address
   • Set risk thresholds (lower for testing: 50, 50, 80)
   • Enable email alerts
   • Save settings
3. Test Alert System:
   • Click "Test Alert" button
   • Watch for spinner and loading state
   • Check your email (and spam folder)
4. Explore Features:
   • View risk map
   • Try disaster simulations
   • Chat with AI assistant
   • Find safe zones

---

📡 API Documentation

Base URL

• Local: http://localhost:8000

Key Endpoints

Disaster Simulation

POST /simulate
Content-Type: application/json

{
  "lat": 20.2961,
  "lon": 85.8245,
  "rainfall_intensity": 50.0,
  "duration_hours": 24,
  "soil_moisture": 0.5,
  "use_live_weather": true
}

Response:
{
  "landslide_risk": 75,
  "flood_risk": 65,
  "risk_level": "HIGH",
  "weather_data": {...}
}

Alert Management

# Save Settings
POST /alert/settings?user_id={user_id}
Content-Type: application/json

{
  "email": "user@example.com",
  "phone": "+1234567890",
  "landslide_threshold": 70,
  "flood_threshold": 60,
  "enable_email": true
}

# Get Settings
GET /alert/settings?user_id={user_id}

# Test Alerts
POST /alert/check?user_id={user_id}
{
  "landslide_risk": 85,
  "flood_risk": 75,
  "rainfall": 120,
  "location": "Location Name"
}

# Debug Settings (Development)
GET /alert/debug

AI Chat

POST /chat
Content-Type: application/json

{
  "message": "What should I do during a flood?",
  "history": []
}

News Feed

GET /news?disaster_type=flood&location=india&max_results=10

API Testing

# Test email system
cd backend
python test_email_quick.py

# Check stored alert settings
curl http://localhost:8000/alert/debug

# Test API health
curl http://localhost:8000/

---

🔧 Troubleshooting

Email Alerts Not Working

Symptoms: Test email script works, but dashboard alerts don't send

Debug Steps:

1. Open browser console (F12) - check logs for:
   • User ID being used
   • Email enabled status
   • "Email actually sent?" result
2. Check backend terminal for:
   • "EMAIL SENT SUCCESSFULLY" message
   • Any error logs
3. Visit http://localhost:8000/alert/debug to verify settings are saved
4. Ensure same user ID is used for saving and testing

Common Causes:

• Settings not saved (backend restarted)
• User ID mismatch
• Email toggle is OFF
• Not logged in (using 'default' instead of actual UID)

See EMAIL_DEBUG_GUIDE.md for detailed debugging.

SMS Not Working

Error: "The number +XXX is unverified"

Solution:

• Verify your phone at: https://www.twilio.com/console/phone-numbers/verified
• Or upgrade Twilio account to remove trial restrictions

CORS Errors

Problem: Frontend can't reach backend

Solutions:

• Verify VITE_API_URL matches your backend URL
• Check backend CORS settings allow your frontend origin
• Ensure both servers are running

Backend Connection Issues

Problem: "Network Error" or "Failed to fetch"

Solutions:

# Verify backend is running
curl http://localhost:8000/

# Check if port 8000 is in use
netstat -ano | findstr :8000  # Windows
lsof -i :8000  # macOS/Linux

Firebase Authentication Issues

Solutions:

1. Enable Email/Password auth in Firebase Console
2. Check Firestore rules allow authenticated access
3. Verify Firebase config in .env

---

📊 Project Structure

kavach/
├── backend/
│   ├── main.py                      # FastAPI application
│   ├── requirements.txt             # Python dependencies
│   ├── .env                         # Environment variables
│   ├── Dockerfile                   # Docker configuration (optional)
│   ├── ml_models/                   # Trained ML models
│   │   ├── flood_regressor.joblib
│   │   └── landslide_classifier.joblib
│   ├── static/                      # Static frontend files
│   ├── test_email_quick.py          # Email testing script
│   └── myenv/                       # Python virtual environment
│
├── frontend/
│   ├── src/
│   │   ├── components/              # React components
│   │   │   ├── charts/              # Chart components
│   │   │   ├── controls/            # Control panels
│   │   │   ├── map/                 # Map components
│   │   │   ├── panels/              # Side panels (Alerts, etc.)
│   │   │   └── ui/                  # Reusable UI components
│   │   ├── pages/                   # Page components
│   │   │   ├── Dashboard/           # Main dashboard
│   │   │   ├── Home/                # Landing page
│   │   │   └── Login/               # Authentication pages
│   │   ├── config/                  # Configuration
│   │   │   ├── firebase.js          # Firebase config
│   │   │   └── index.js
│   │   ├── services/                # API services
│   │   │   ├── api.service.js       # Backend API calls
│   │   │   └── auth.service.js      # Auth services
│   │   ├── context/                 # React contexts
│   │   │   └── Authcontext/         # Authentication context
│   │   ├── hooks/                   # Custom React hooks
│   │   ├── utils/                   # Utility functions
│   │   └── styles/                  # Global styles
│   ├── public/                      # Public assets
│   ├── package.json                 # Node dependencies
│   ├── vite.config.js               # Vite configuration
│   ├── firebase.json                # Firebase config
│   ├── firestore.rules              # Firestore security rules
│   └── .env                         # Environment variables
│
├── README.md                        # This file
├── ALERT_SYSTEM_FLOW.md             # Alert system documentation
├── ALERT_SYSTEM_FIXED.md            # Alert fixes documentation
└── EMAIL_DEBUG_GUIDE.md             # Email debugging guide

---

🤝 Contributing

We welcome contributions! Here's how you can help:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Development Guidelines

• Follow existing code style
• Add comments for complex logic
• Test thoroughly before submitting
• Update documentation as needed
• Use conventional commit messages

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

👥 Team

• Developer: Subham Nabik
• Email: nabiksubham2005@gmail.com
• Institution: [Your Institution Name]

---

🙏 Acknowledgments

• Google Gemini AI for intelligent disaster guidance
• Resend for reliable email delivery
• Twilio for SMS services
• Open-Meteo for weather data
• Firebase for authentication and database
• scikit-learn community for ML tools
• React and FastAPI communities

---

📞 Support

For issues, questions, or suggestions:

• GitHub Issues: Create an issue on the repository
• Email: nabiksubham2005@gmail.com
• Documentation: Check the /docs folder for detailed guides

---

🔮 Future Enhancements

• Mobile app (React Native)
• Real-time earthquake monitoring
• Drone integration for disaster assessment
• Community reporting system
• Offline mode for emergency situations
• Multi-language support (Hindi, regional languages)
• Integration with government emergency services
• Advanced ML models (Deep Learning, LSTM for time-series)
• Historical disaster data analysis
• Predictive analytics dashboard
• WebSocket support for real-time updates
• Push notifications for mobile

---

📈 Performance Metrics

• Backend Response Time: < 500ms (average)
• ML Model Inference: < 200ms
• Email Delivery: 5-30 seconds
• SMS Delivery: 10-60 seconds
• Frontend Load Time: < 2s
• Supported Concurrent Users: 100+

---

🔐 Security

• Firebase Authentication with secure token management
• Environment variables for sensitive data
• HTTPS/SSL for all production deployments
• CORS configuration for authorized origins only
• Firestore security rules for data protection
• Input validation and sanitization
• Rate limiting on API endpoints

---

Made with ❤️ for Disaster Preparedness

Save Lives • Protect Communities • Build Resilience

---

⭐ Star this repository if you found it helpful!

Report Bug · Request Feature · Documentation