SafeStreets - Route Risk Prediction System

A comprehensive web application that predicts accident risk along routes using machine learning, real-time weather data, and historical accident patterns.

🚀 Features

Core Functionality

• Interactive Map: Click to set start and end points for route planning
• Real-time Risk Analysis: ML-powered accident risk assessment
• Live Weather Integration: Real weather data from OpenWeatherMap API
• Historical Hotspots: Visual heatmap of accident-prone areas
• Route Alternatives: Compare multiple route options for safety

Advanced Features

• Weather Caching: 30-minute cache to reduce API calls
• Error Recovery: Graceful fallback when APIs are unavailable
• Data Validation: Comprehensive input validation and range checking
• Health Monitoring: Built-in health checks and logging
• Docker Support: Complete containerization for easy deployment

🎯 Risk Levels

• 🟢 Low Risk: Safe driving conditions (Score: 80-100)
• 🟡 Medium Risk: Moderate caution advised (Score: 50-79)
• 🔴 High Risk: Dangerous conditions, avoid if possible (Score: 0-49)

🚀 Quick Start

Option 1: Docker (Recommended)

# Clone and run with Docker
git clone <repository>
cd SafeStreets
docker-compose up --build

Access at: http://localhost

Option 2: Manual Setup

# Install dependencies
pip install -r requirements.txt

# Start backend
cd backend
python app.py

# Start frontend (new terminal)
cd frontend
python -m http.server 8000

Access at: http://localhost:8000

🔧 Configuration

Environment Variables

Copy .env.example to .env and configure:

cp .env.example .env

Key settings:

• OPENWEATHER_API_KEY: Get from OpenWeatherMap
• WEATHER_CACHE_DURATION: Cache duration in seconds (default: 1800)
• API_HOST/API_PORT: Backend server configuration

Weather API Setup (Optional)

1. Register at OpenWeatherMap
2. Get your free API key
3. Add to .env: OPENWEATHER_API_KEY=your_key_here
4. Restart the application

📊 API Endpoints

• GET / - API status
• GET /health - Health check with model status
• GET /weather/<lat>/<lon> - Get weather data for coordinates
• POST /predict - Predict accident risk with weather data

🧪 Testing

Run Unit Tests

cd tests
python test_api.py

Test Coverage

• API endpoint testing
• Data validation testing
• Weather function testing
• Error handling testing

🐳 Docker Deployment

Production Deployment

# Build and start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Service Architecture

• Frontend: Nginx serving static files on port 80
• Backend: Flask API on port 5000
• Network: Internal Docker network for service communication

📁 Project Structure

SafeStreets/
├── backend/
│   ├── app.py              # Flask API server with weather integration
│   └── (enhanced with caching, validation, error handling)
├── frontend/
│   ├── index.html          # Enhanced web interface
│   ├── script.js           # Real weather API calls, route alternatives
│   ├── style.css           # Modern styling with animations
│   └── accident_hotspots.json  # Heatmap data
├── tests/
│   └── test_api.py        # Comprehensive unit tests
├── model/
│   ├── accident_model.pkl  # Trained ML model
│   └── train_model.py      # Model training script
├── docker-compose.yml      # Multi-service orchestration
├── Dockerfile             # Multi-stage build configuration
├── nginx.conf            # Frontend web server configuration
├── requirements.txt       # Updated Python dependencies
└── .env.example         # Environment configuration template

🔬 Technical Details

Enhanced Backend

• Weather Integration: OpenWeatherMap API with 30-minute caching
• Error Recovery: Automatic fallback to simulated data
• Input Validation: Comprehensive range checking for all parameters
• Logging: Structured logging with different levels
• Health Checks: Built-in monitoring endpoints

Improved Frontend

• Real Weather: API calls to backend for live weather data
• Route Alternatives: Compare multiple route options
• Better UX: Loading states, error messages, smooth animations
• Responsive Design: Works on desktop and mobile devices

ML Model

• Algorithm: Random Forest Classifier
• Features: Temperature, humidity, visibility, wind speed, precipitation
• Training: US accident records with weather conditions
• Validation: Input range validation and error handling

🚀 New Features Added

Weather Integration

• Real-time weather data from OpenWeatherMap
• Automatic fallback to simulated data
• 30-minute caching to reduce API calls
• Seasonal and geographic variations

Route Alternatives

• Compare multiple route options
• Safety scores for each alternative
• Time vs safety trade-offs
• Interactive route selection

Enhanced Error Handling

• Graceful degradation when APIs fail
• Comprehensive input validation
• User-friendly error messages
• Automatic retry logic

Production Ready

• Docker containerization
• Nginx reverse proxy
• Health checks and monitoring
• Optimized static asset serving

🔮 Future Enhancements

• Traffic data integration
• Real-time route optimization
• Mobile app development
• User authentication and saved routes
• Historical route analysis
• Machine learning model improvements

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

📄 License

This project is for educational purposes. Please ensure compliance with data usage terms for accident datasets and weather APIs.