Stay ahead of nature's fury. NaturAlert is an intelligent early warning system that combines machine learning, real-time weather data, and AI-powered insights to predict natural disasters before they strike. Whether you're tracking a hurricane, monitoring flood risks, or preparing for extreme weather, NaturAlert gives you the information you need to stay safe.
Natural disasters claim thousands of lives and cause billions in damage every year. The difference between safety and catastrophe often comes down to minutes of warning. NaturAlert bridges that gap by analyzing weather patterns, historical disaster data, and current conditions to deliver accurate, actionable risk assessments in real-time.
NaturAlert is built on the principle that life-saving technology should be accessible to everyone. We use open-source tools, public datasets, and transparent methodologies to ensure our work can be replicated, improved, and adapted by communities worldwide.
Backend Infrastructure
Python 3.9+ powers our FastAPI backend, delivering lightning-fast API responses. Machine learning models built with scikit-learn analyze weather patterns, while Google Gemini AI provides intelligent conversational insights. Data persistence handled by SQLite in development and PostgreSQL for production deployments.
Frontend Experience
React 18 with Vite ensures a blazing-fast, responsive user interface. Globe.gl brings stunning 3D visualizations to life, while Tailwind CSS provides a clean, modern design. Firebase Authentication keeps your data secure, and WebSocket integration delivers real-time updates as conditions change.
Data Sources
Real-time weather data from Open-Meteo and OpenWeather APIs ensures accuracy and reliability. Historical disaster data helps our models learn from past events to predict future risks.
What You'll Need
Python 3.9 or higher, Node.js 18 or higher, and Git. That's it.
Installation
Clone and set up the project:
# Get the code
git clone https://github.com/tungle2709/NaturAlert.git
cd NaturAlert
# Install backend dependencies
pip install -r requirements.txt
# Install frontend dependencies
cd frontend
npm install --legacy-peer-deps
cd ..
# Optional: Add your Gemini API key for AI features
cp .env.example .env
# Edit .env and add your GEMINI_API_KEYLaunch the Application
Start the backend server:
python3 backend/app.pyThe API will be available at http://localhost:8000
In a new terminal, start the frontend:
cd frontend
npm run devThe app will open at http://localhost:5173
Open your browser and start exploring. No complex configuration required.
NaturAlert provides a RESTful API for developers who want to integrate disaster prediction into their own applications:
GET /health- Check system status and uptimeGET /api/v1/risk/current- Get real-time risk assessment for any locationGET /api/v1/risk/trends- Access historical trend analysis and patternsPOST /api/v1/gemini/chat- Interact with the AI assistant programmaticallyGET /docs- Explore interactive API documentation with live examples
Visit http://localhost:8000/docs when running locally to test endpoints in your browser.
Project Architecture
The codebase is organized for clarity and maintainability:
├── backend/ # FastAPI server and business logic
│ ├── services/ # ML models, AI integration, weather APIs
│ ├── database/ # Data persistence and schema
│ └── app.py # Application entry point
├── frontend/ # React application
│ ├── src/ # Components, services, and utilities
│ └── public/ # Static assets and resources
├── models/ # Trained machine learning models
└── requirements.txt # Python package dependencies
Contributing to NaturAlert
We welcome contributions that make disaster prediction more accurate and accessible:
- Fork the repository and create a feature branch
- Write clean, documented code that follows existing patterns
- Test your changes thoroughly—lives may depend on this system
- Submit a pull request with a clear description of your improvements
Whether you're fixing bugs, adding features, or improving documentation, your contributions help make the world safer.
NaturAlert - Because everyone deserves a warning.