A real-time water level monitoring system for smallholder farmers in Limpopo, South Africa. Built to prevent crop failures by predicting water shortages before they happen.
Rural farmers in Limpopo rely on boreholes for irrigation, but they have no way to know when water levels are critically low until it's too late. This app solves that by:
- Real-time water level tracking with WebSocket updates
- AI-powered predictions (7-day forecast using Gemini)
- SMS/push alerts when levels hit critical thresholds
- Simple, mobile-first UI that works offline
- Multi-language support (English, Sepedi, Tswana)
Right now we're simulating sensor data because we don't have physical IoT sensors deployed yet, but the backend is built to handle real sensor ingestion when we scale up.
Frontend:
- React 18 with React Router
- Tailwind CSS for styling
- Socket.io client for real-time updates
- Recharts for data visualization
- Inter font (Google Fonts)
Backend:
- Flask + Flask-SocketIO
- SQLite (dev) / PostgreSQL (production)
- JWT authentication
- APScheduler for background tasks
- Gemini AI for predictions
AI Agents:
- Sensor simulation (water level, flow meter, rainfall)
- Weather generation (Limpopo-specific patterns)
- Prediction model (aquifer physics + ML)
cd backend
python -m venv venv
source venv/bin/activate # or venv\Scripts\activate on Windows
pip install -r requirements.txt
# Set your Gemini API key
export GEMINI_API_KEY="your-key-here"
# Initialize database
flask db upgrade
# Run dev server
python app.pyBackend runs on http://localhost:5000
npm install
npm run devFrontend runs on http://localhost:3000
future_hackers/
├── backend/
│ ├── agents/ # AI simulation agents
│ │ ├── sensor_agent.py
│ │ ├── weather_agent.py
│ │ └── prediction_agent.py
│ ├── routes/ # API endpoints
│ ├── models.py # Database models
│ └── app.py
│
├── src/
│ ├── components/
│ │ ├── BoreholeCard.jsx # Main card with water tank viz
│ │ ├── WaterTankVisual.jsx # Animated 3D water tank
│ │ ├── DashboardSummary.jsx # Stats overview
│ │ └── CircularProgress.jsx # Fallback progress indicator
│ ├── pages/
│ │ └── Dashboard.jsx # Main dashboard page
│ ├── hooks/
│ │ └── useBoreholeSocket.js # WebSocket hook
│ └── index.css # Design system + animations
- WebSocket connection updates water levels every few seconds
- Animated water tank visualization shows current capacity
- Risk-based color coding (green = safe, amber = warning, red = critical)
- 7-day water level forecast
- Confidence intervals based on aquifer type
- Considers rainfall, temperature, usage patterns, and seasonal factors
- Farmer-friendly recommendations ("Reduce irrigation by 20%")
- Critical/warning thresholds configurable per borehole
- SMS notifications via Twilio (when enabled)
- Browser push notifications
- In-app alert panel
- PWA with service workers (coming soon)
- Cached data for viewing when network drops
- Background sync when connection returns
Since we don't have physical sensors yet, AI agents simulate realistic data:
- Water Level: Drops based on daily usage, rises with rainfall
- Rainfall: Limpopo-specific patterns (rainy Oct-Mar, dry Apr-Sep)
- Flow Meter: Simulates irrigation patterns (peaks at 6-9am, 5-7pm)
- Aquifer Physics: Unconfined (fast recharge) vs confined (slow recharge)
Background scheduler runs every hour to generate new readings.
Gemini AI analyzes:
- Current water level + 30-day history
- Recent rainfall (7 days)
- Temperature forecast
- Daily water usage patterns
- Aquifer type and recharge rate
- Crop type and growth stage
- Seasonal evapotranspiration
Outputs:
- 7-day forecast with high/low bounds
- Risk assessment per day
- Days until critical (if trending down)
- Actionable recommendations
Built an endpoint for when physical sensors come online:
POST /api/sensors/reading
{
"sensor_id": "BH001-WL",
"borehole_id": 1,
"water_level_meters": 12.5,
"timestamp": "2025-10-14T10:30:00Z"
}Backend handles both simulated and real data (tracks with is_simulated flag).
- Primary: Sky blue (#0EA5E9) - professional, not harsh
- Success: Emerald (#10B981) - safe water levels
- Warning: Amber (#F59E0B) - caution
- Danger: Red (#EF4444) - critical levels
- Font: Inter with OpenType features
- Hierarchy: 72px titles, 48px names, 16px body, 12px labels
- Weight: Mostly font-bold/font-black for clarity
animate-wave: Water surface ripple effectanimate-shimmer: Shine effect on buttons/wateranimate-gentle-pulse: Breathing effect for critical alertsanimate-slide-in-right: Toast notifications
All animations respect prefers-reduced-motion for accessibility.
Dashboard has an "Add Borehole" button that opens a form:
- Name, location (district), GPS coordinates
- Depth, aquifer type (confined/unconfined)
- Crop type(s), farm size, daily water usage
Click "Check Water Level" on any borehole card:
- Triggers sensor reading simulation
- Stores new data point
- Calls prediction agent
- Updates forecast chart
- Generates alerts if thresholds crossed
Use admin controls (hidden by default) to simulate:
- Drought conditions (10 days no rain)
- Heavy rainfall (50mm storm)
- Pump failure (usage drops to 0)
- Fast-forward time
- Flow meter simulation needs more realistic time-of-day patterns
- SMS notifications not fully integrated (Twilio setup pending)
- Offline PWA features incomplete
- Multi-language i18n not implemented yet
- Some clipping issues on very small screens (<360px)
- Set
FLASK_ENV=production - Add Gemini API key to environment
- Switch to PostgreSQL database
- Enable CORS for frontend domain
- Build:
npm run build - Output:
dist/folder - Set API base URL to backend domain
This project is for a hackathon focused on rural farmer solutions. If you want to contribute:
- Keep the UI simple - target users have limited tech literacy
- Optimize for mobile and low bandwidth
- Test with slow 3G speeds
- Consider offline scenarios
- Use clear, non-technical language
MIT - use it, fork it, improve it.
Built by the Future Hackers team for Limpopo farmers.
Important: This is NOT a prototype. We're building production-ready software that farmers will depend on to save their crops. Every alert matters.