RainWise

RainWise is a rooftop rainwater harvesting (RTRWH) feasibility assessment tool.
Enter your location, roof area, and household size to get a full report covering predicted harvestable volume, groundwater recharge recommendations, financial analysis, and aquifer data.

A single Flask service serves both the frontend UI and the API — no separate server required.

Features

• Real weather data — last 365 days of precipitation, temperature, and humidity pulled from the Open-Meteo Archive API, aggregated into real monthly distributions
• ML harvest prediction — Gradient Boosting model (R² = 0.9912, CV R² = 0.9907) trained on 5,000 physics-based samples covering first-flush losses, evaporation, and open-space percolation
• Interactive map — Leaflet map auto-pans to the geocoded location
• Dynamic charts — monthly historical vs. predicted rainfall bar chart; 5-year cumulative savings line chart
• Full financial analysis — installation cost, payback period, 20-year ROI
• Structure recommendations — context-aware suggestions (recharge pit, storage tank, percolation trench, etc.)
• Live model stats — ML accuracy table and feature importance bar chart rendered from actual model metadata

Project Structure

backend/
  app.py            Flask API + static file serving
  train_model.py    Model training script (run once before starting the server)
  rf_model.joblib   Trained model + metadata (generated by train_model.py)
  wsgi.py           WSGI entrypoint
  requirements.txt  Python dependencies
public/
  index.html        Web UI
  script.js         Client logic, charts, and map
  styles.css        UI styling

Prerequisites

• Python 3.11+

Setup

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

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

# 3. Train the ML model (required before first run)
python backend/train_model.py

Run

python backend/app.py

Open http://127.0.0.1:5000 in your browser.

Environment Variables

Variable	Default	Description
PORT	5000	Port to listen on
HOST	0.0.0.0	Host to bind to
FLASK_DEBUG	false	Enable Flask debug mode
USE_WAITRESS	true	Use Waitress WSGI server (recommended for production on Windows)
ENABLE_CORS	false	Enable CORS headers (set true if frontend is served separately)
APP_USER_AGENT	RainWise/1.0	User-Agent sent to the Nominatim geocoding API

API Endpoints

GET /api/health

Returns server status and model info.

{
  "status": "ok",
  "service": "rainwise",
  "model_loaded": true,
  "model_name": "Gradient Boosting"
}

POST /api/calculate

{
  "name": "John Doe",
  "city": "Delhi",
  "country": "India",
  "dwellers": 4,
  "roof_area": 100,
  "open_space": 50,
  "year": 2026
}

Returns full feasibility report including harvestable_volume, feasibility, monthly_rainfall, structures, aquifer, financial metrics, and model_info.

ML Model

The harvest prediction model is trained by backend/train_model.py:

• Algorithm: Gradient Boosting (300 trees, learning rate 0.05) — chosen automatically over Random Forest based on test R²
• Training data: 5,000 physics-based synthetic samples
• Physics modelled: first-flush losses, evaporation (temperature + humidity driven), open-space percolation, dwelling-scale factor
• Performance: R² = 0.9912 · CV R² = 0.9907 · RMSE ≈ 31,000 L/yr
• Top features: Annual Rainfall (52%), Roof Area (41%), Open Space (3%), Runoff Coefficient (3%)

Retrain at any time:

python backend/train_model.py

Deployment

• The app is a single Python process — no Node.js or separate frontend build needed.
• rf_model.joblib (~2 MB) is committed to the repo, so no extra training step is needed after deploy.
• A Procfile is included for platforms that use it (Heroku, Railway, Render).
• On Windows, Waitress is used automatically when FLASK_DEBUG=false.
• On Linux/macOS, wrap with Gunicorn: gunicorn --chdir backend wsgi:app --bind 0.0.0.0:$PORT
• If deploying behind a reverse proxy (Nginx, Caddy, etc.), forward traffic to HOST:PORT and set ENABLE_CORS=false.
• The PORT environment variable is respected, so platform-managed ports work out of the box.