🔥 Wildfire Intelligence Platform

AI-powered fire weather monitoring and spread simulation system for the Western Ghats forest reserves.

---

📖 Overview

The Wildfire Intelligence Platform is a full-stack geospatial intelligence system that combines real-time weather ingestion, machine learning fire-risk prediction, satellite fire detection (NASA FIRMS), and a physics-based cellular automata fire spread simulator — all presented in a glassmorphic, interactive dashboard.

It was built specifically to monitor fire-prone forest reserves across the Western Ghats of India, providing actionable risk intelligence to ecologists, forest rangers, and fire management teams.

---

✨ Key Features

Feature	Description
🌡️ Real-time Weather Ingestion	Pulls temperature, humidity, wind, and rainfall from Open-Meteo at 15-minute intervals
🛰️ NASA FIRMS Integration	Ingests active fire detections (VIIRS/MODIS) from NASA's Fire Information for Resource Management System
🌿 NDVI Monitoring	Vegetation greenness index tracking via satellite-derived fuel moisture proxy
🤖 ML Fire Risk Prediction	XGBoost model with SHAP explainability providing per-station fire risk probability
🧪 Anomaly Detection	Isolation Forest detects abnormal meteorological conditions preceding fire events
💧 Fuel Moisture Estimation	Random Forest model estimating live fuel moisture content from weather variables
🗺️ Fire Spread Simulator	Physics-based Cellular Automata (CA) simulation with wind vector, slope, and dryness acceleration
📊 Interactive Analytics	SHAP waterfall charts, gauge indicators, trend analytics, and telemetry panels
🖥️ Glassmorphic Dashboard	Modern, responsive UI with real-time data across Overview, Map, Analytics, Trends, Simulation, and Operations views

---

🏗️ Architecture

wildfire-intelligence/
├── backend/                  # FastAPI Python backend
│   ├── app/
│   │   ├── routers/          # REST API route handlers
│   │   │   ├── health.py     # System health & DB connectivity
│   │   │   ├── stations.py   # Station metadata & FFWI readings
│   │   │   ├── readings.py   # Time-series weather data
│   │   │   ├── predictions.py# ML fire risk predictions
│   │   │   ├── detections.py # NASA FIRMS fire detections
│   │   │   ├── simulation.py # Fire spread simulation engine
│   │   │   └── models.py     # Model cards & performance metrics
│   │   ├── engines/
│   │   │   ├── ffwi.py       # Fosberg Fire Weather Index engine
│   │   │   ├── fire_season.py# Fire season calendar logic
│   │   │   └── risk_bands.py # Risk band classification (Low→Critical)
│   │   ├── ingestion/
│   │   │   ├── open_meteo.py # Open-Meteo weather data ingestion
│   │   │   ├── ndvi.py       # NDVI satellite data ingestion
│   │   │   ├── fsi.py        # Fire Season Index computation
│   │   │   └── scheduler.py  # APScheduler background task runner
│   │   ├── main.py           # FastAPI app entry point
│   │   ├── config.py         # Pydantic settings management
│   │   └── database.py       # SQLAlchemy async session factory
│   └── ml/
│       ├── train_xgboost.py       # Fire risk XGBoost trainer
│       ├── train_isolation_forest.py # Anomaly detection trainer
│       ├── train_fuel_moisture.py # Fuel moisture Random Forest trainer
│       ├── feature_engineering.py # Shared feature pipeline
│       └── shap_explainer.py      # SHAP value computation
│
└── frontend/                 # React + TypeScript + Vite frontend
    └── src/
        ├── views/
        │   ├── Overview.tsx   # Station grid with FFWI risk cards
        │   ├── MapView.tsx    # MapLibre GL interactive fire map
        │   ├── Analytics.tsx  # SHAP, anomaly & fuel moisture panels
        │   ├── Trends.tsx     # Historical weather trend charts
        │   ├── Simulation.tsx # Interactive fire spread simulator
        │   └── Operations.tsx # Data pipeline & model ops status
        ├── styles/
        │   ├── tokens.css     # Design system CSS custom properties
        │   └── glassmorphism.css
        ├── hooks/             # Custom React data hooks
        └── utils/             # Shared utilities

---

🧠 Machine Learning Models

1. XGBoost Fire Risk Classifier

Predicts the probability of fire ignition at each station over the next 24 hours using weather and terrain features. SHAP values provide per-prediction explanations visible directly in the Analytics view.

Key Features: Temperature, Relative Humidity, Wind Speed, FFWI score, NDVI, Rainfall (7-day), Fire Season flag.

2. Isolation Forest Anomaly Detector

Detects statistically anomalous weather patterns (e.g., sudden temperature spike + humidity drop) that historically precede fire events, even when individual values appear within normal range.

3. Random Forest Fuel Moisture Estimator

Estimates live fuel moisture content (%) from meteorological inputs. Dry fuel (<15% moisture) accelerates fire spread dramatically in the simulation engine.

---

🗺️ Fire Spread Simulation

The simulation engine implements a physics-based Cellular Automata model on a high-resolution geospatial grid over the selected reserve:

• Wind Vector Acceleration: Spread rate multiplied in downwind directions using the wind azimuth
• Terrain Slope: Uphill spread is geometrically accelerated (tilted flame pre-heating)
• Fuel Moisture: Drier cells (from ML model output) have shorter transit times between grid nodes
• Fosberg Fire Weather Index (FFWI): Real-time scalar that gates overall spread intensity
• Interactive Controls: Click ignition origin, adjust wind speed/direction, playback timeline scrubber, and real-time elapsed timer

---

🚀 Getting Started

Prerequisites

• Python 3.11+
• Node.js 18+ and npm
• PostgreSQL 15+ (with PostGIS recommended)
• NASA FIRMS API key → Register here

---

1. Clone the Repository

git clone https://github.com/Nekilesh001/forest-fire-ai.git
cd forest-fire-ai

---

2. Backend Setup

# Create and activate virtual environment
python -m venv .venv
.venv\Scripts\activate        # Windows
# source .venv/bin/activate   # macOS/Linux

# Install dependencies
pip install -r backend/requirements.txt

# Configure environment variables
cp .env.example .env
# Edit .env with your database credentials and NASA FIRMS key

.env Configuration

Variable	Description	Default
POSTGRES_HOST	PostgreSQL host	localhost
POSTGRES_PORT	PostgreSQL port	5432
POSTGRES_DB	Database name	wildfire
POSTGRES_USER	DB username	postgres
POSTGRES_PASSWORD	DB password	(required)
NASA_FIRMS_KEY	NASA FIRMS API key	(required)
ALLOWED_ORIGINS	CORS origins	http://localhost:5173
LOG_LEVEL	Logging verbosity	INFO

Run the Backend

# From project root
uvicorn backend.app.main:app --reload --host 0.0.0.0 --port 8000

API docs available at: http://localhost:8000/docs

---

3. Train ML Models

Run training scripts before launching the backend for the first time (or whenever you want to retrain on updated data):

cd backend
python -m ml.train_xgboost
python -m ml.train_isolation_forest
python -m ml.train_fuel_moisture

---

4. Frontend Setup

cd frontend

# Install dependencies
npm install

# Start development server
npm run dev

Frontend runs at: http://localhost:5173

---

5. Production Build

cd frontend
npm run build
# Output in frontend/dist/

---

🌐 API Endpoints

Method	Endpoint	Description
GET	/api/health	System health and DB connectivity check
GET	/api/stations	All monitoring stations with latest readings
GET	/api/stations/{id}/readings	Time-series weather data for a station
GET	/api/predictions/{station_id}	ML fire risk predictions
GET	/api/detections	NASA FIRMS active fire detections
POST	/api/simulation/run	Run a fire spread simulation
GET	/api/models	Model cards and performance metrics

Full interactive API documentation: /docs (Swagger UI) or /redoc

---

📊 Dashboard Views

View	Description
Overview	Station grid cards with FFWI score, risk band, and 4-metric weather summary
Map	Real-time interactive MapLibre GL map with fire detections and spread simulation overlay
Analytics	SHAP waterfall explanations, Isolation Forest anomaly indicator, fuel moisture gauge
Trends	Historical time-series charts with extreme value panels
Simulation	Interactive fire spread simulator with wind/terrain physics controls
Operations	Data pipeline health, ingestion schedules, model performance metrics

---

🛠️ Tech Stack

Backend

• FastAPI — Async REST API framework
• SQLAlchemy (Async) — ORM and database session management
• PostgreSQL — Primary time-series and geospatial data store
• APScheduler — Background scheduler for weather ingestion
• XGBoost — Gradient boosting fire risk classifier
• scikit-learn — Isolation Forest and Random Forest models
• SHAP — Model explainability and feature attribution
• Loguru — Structured application logging

Frontend

• React 19 + TypeScript — UI framework
• Vite — Build tool and development server
• MapLibre GL JS — Open-source WebGL interactive mapping
• Deck.gl — GPU-accelerated geospatial visualization layers
• D3.js — Custom data-driven charts and gauges
• React Router v7 — Client-side navigation
• Tailwind CSS — Utility-first styling with custom design tokens

---

📁 Data Sources

Source	Data Type	Update Frequency
Open-Meteo	Temperature, Humidity, Wind, Rainfall	Every 15 minutes
NASA FIRMS	VIIRS/MODIS active fire detections	Daily
Copernicus/Sentinel	NDVI vegetation index	Weekly/On-demand

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Commit changes: git commit -m "Add my feature"
4. Push to branch: git push origin feature/my-feature
5. Open a Pull Request

Please ensure backend changes include unit tests in backend/tests/ and frontend changes follow the existing component patterns.

---

📜 License

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

---

🙏 Acknowledgements

• NASA FIRMS for open access fire detection data
• Open-Meteo for free, open weather API
• MapLibre GL for the open-source mapping engine
• The Western Ghats forest ecology community for domain expertise

---

Built with ❤️ for forest fire intelligence and conservation.