AI-based multi-hazard disaster prediction and early warning platform for real-time monitoring, explainable forecasts, and operational response.

Vigil combines live weather inputs, trained ML artifacts, and rule/API hazard engines into a unified decision-support system for disaster risk intelligence.

• Frontend: React 18 + TypeScript + Vite + Tailwind + shadcn/ui
• Backend: FastAPI + SQLAlchemy + JWT auth
• ML/XAI: scikit-learn, XGBoost, LightGBM, SHAP
• Maps/Visualization: react-leaflet + Recharts

This repository is actively maintained and in a strong demo-ready state.

• Completed: End-to-end authenticated flow and protected API checks
• Completed: Multi-hazard prediction coverage in UI and API (including wildfire and hurricane tabs)
• Completed: Novelty outputs propagated in prediction insights (SCBC, ARTC, CWEF diagnostics)
• Completed: Dashboard stats integrity improvements (model ROC-AUC aggregation, monitored regions alignment)
• Completed: 15 monitored Indian regions in baseline region set
• Completed: Frontend quality gate cleanup (lint/type-check stability improvements)
• In progress: Dataset admin training-job orchestration (upload and registry are present; deeper train/status/download workflow is being expanded)

Corrects raw real-time weather features against monthly climatological baselines before inference.

• File: backend/ml/climate_baseline.py
• Output fields surfaced through insights: seasonal_correction_applied, scbc_month

Adds hazard cascade-aware ensemble fusion for compound risk estimation.

• File: backend/ml/ensemble_fusion.py
• Output fields surfaced through insights: cwef_score, dominant_hazard, cascade_chain, cascade_triggered, individual_weights

Replaces static thresholds with geography- and hazard-aware risk classification profiles.

• File: backend/ml/adaptive_threshold.py
• Output field surfaced through insights: zone_profile

Frontend (React + Vite, :8080)
  -> src/lib/api.ts (typed API client via Axios)
  -> FastAPI backend (:8000, /api/v1/*)
      -> SQLAlchemy models / PostgreSQL
      -> ML estimators + model artifacts
      -> External data: Open-Meteo, OpenWeatherMap, NASA FIRMS

• src/pages/dashboard/predictions/*: Hazard prediction pages
• src/pages/dashboard/satellite/SatelliteViewerPage.tsx: Map overlays and satellite/weather layers
• src/pages/dashboard/admin/*: Admin modules (users/system/datasets/models)
• backend/api/routes/*: API route modules
• backend/ml/*: Inference and novelty logic
• backend/scripts/*: Training, ingestion, and operational scripts

• Node.js 18+
• npm 9+
• Python 3.11+
• PostgreSQL 14+

npm install

From repository root:

pip install fastapi uvicorn sqlalchemy pydantic pydantic-settings pyjwt passlib email-validator python-multipart httpx pandas numpy scikit-learn xgboost lightgbm shap joblib imbalanced-learn optuna boto3 psycopg2-binary

Create/update both env files.

Root .env:

VITE_API_BASE_URL=http://localhost:8000/api/v1
VITE_OPENWEATHER_API_KEY=your_openweather_api_key

backend/.env:

APP_NAME=Vigil
DEBUG=False
SECRET_KEY=replace_with_32_plus_char_random_secret
DATABASE_URL=postgresql://user:password@localhost:5432/vigil_db
OPENWEATHER_API_KEY=your_openweather_api_key
NASA_FIRMS_MAP_KEY=your_nasa_firms_map_key
CORS_ORIGINS=http://localhost:8080,http://127.0.0.1:8080

npm run dev:full

Starts:

• Frontend: http://localhost:8080
• Backend API: http://localhost:8000

npm run dev:frontend

npm run dev:backend

After startup, verify these endpoints and pages:

1. GET http://localhost:8000/health
2. Login flow works at /auth/login
3. GET /api/v1/dashboard/stats (authenticated)
4. Prediction insights endpoint returns novelty metadata for compound requests
5. Dashboard map renders monitored regions and risk overlays

Core model scripts:

python backend/scripts/train_flood_model.py
python backend/scripts/train_cyclone_model.py
python backend/scripts/train_drought_model.py
python backend/scripts/train_heatwave_model.py
python backend/scripts/train_compound_model.py

Optional operational scripts:

python backend/scripts/prepare_all.py
python backend/scripts/sanity_check_predictions.py
python backend/scripts/seed_dashboard.py

npm run lint
npm run test
npx tsc --noEmit
npm run build

Primary route groups under /api/v1:

• /auth
• /dashboard
• /predictions
• /weather
• /alerts
• /models
• /datasets
• /regions
• /analytics
• /xai
• /admin
• /community
• /search
• /federated

• If weather endpoints fail: validate OPENWEATHER_API_KEY and outbound network access.
• If dashboard data is empty: verify authentication token and database connectivity.
• If model accuracy appears null: ensure local artifact files exist and include roc_auc metadata.
• If satellite weather overlays are missing: set VITE_OPENWEATHER_API_KEY in root .env.

• Do not commit real API keys or database credentials.
• Keep .env files local and rotate keys if exposed.
• Production deployments should set strict CORS and secure secret management.

• Finalize full dataset-admin training workflow (train/status/download lifecycle)
• Continue model retraining audits on expanded real-data windows
• Maintain parity checks between UI values and authenticated API outputs

Vigil is built as a research-to-operations platform for practical, explainable, and extensible multi-hazard risk intelligence.