_    ___     _______  _____   ____     ____  _____  ____ _____ _______
| |  | \ \   / /  __ \|  __ \ / __ \   / __ \|  __ \|  _ \_   _|__   __|
| |__| |\ \_/ /| |  | | |__) | |  | | | |  | | |__) | |_) || |    | |   
|  __  | \   / | |  | |  _  /| |  | | | |  | |  _  /|  _ < | |    | |   
| |  | |  | |  | |__| | | \ \| |__| | | |__| | | \ \| |_) || |_   | |   
|_|  |_|  |_|  |_____/|_|  \_\\____/   \____/|_|  \_\____/_____|  |_|

Hydro‑Orbit

Solar‑powered, AI‑driven smart irrigation for smallholder farmers.

Why? • Features • Architecture • Quick Start • Tech Stack • Roadmap • Contributing

---

Hydro‑Orbit is a complete, open‑source smart irrigation platform built for smallholder farmers in water‑stressed regions. It combines ESP32‑based soil sensors, a fuzzy‑logic AI engine, a real‑time web dashboard, and a mobile app to deliver precise, automated irrigation — all powered by solar energy and designed for off‑grid deployment.

Unlike closed commercial systems, Hydro‑Orbit gives you full control: modify the firmware, train your own AI models, build custom dashboards, or deploy the entire stack on a Raspberry Pi.

---

Why Hydro‑Orbit?

In Rwanda, only 27–31% of irrigable land receives adequate water. Smallholder farmers — who produce 80% of the country's food — rely on rain‑fed agriculture that is increasingly unreliable due to climate change. Commercial irrigation systems are expensive, proprietary, and designed for large industrial farms.

Hydro‑Orbit was built to change that:

Problem	Our Solution
Expensive proprietary hardware	Open‑source ESP32 + sensors — ~$50 per node
Complex installation	Solar‑powered, wireless — works off‑grid
No real‑time visibility	Web + mobile dashboard with live sensor data
Wasted water	AI‑driven scheduling reduces usage by up to 31%
One‑size‑fits-all	Configurable zones for different crops and soil types

What makes Hydro‑Orbit different?

• Fully open source — hardware, firmware, backend, AI, and frontend
• Greywater‑ready — designed to safely integrate treated household greywater
• Solar‑native — low‑power ESP32 with solar charging
• AI at the edge — fuzzy logic runs on the ESP32; advanced LSTM predictions on the server
• Turborepo monorepo — clean, modern TypeScript stack from database to UI

---

✨ Key Features

Category	Feature	Description
⚡ Hardware	Solar‑Powered	ESP32 with deep‑sleep, solar charging, ~2W average draw
💧 Irrigation	AI‑Optimized	Fuzzy logic + LSTM predicts soil moisture and schedules watering
📡 Monitoring	Real‑Time Sensors	Soil moisture, pH, water level, battery — updated every 30s
🌐 Connectivity	MQTT + WiFi	Reliable pub‑sub messaging; works with any MQTT broker
📊 Dashboard	Web App	React + Vite dashboard with charts, alerts, and farm map
📱 Mobile	Expo App	Native mobile experience for iOS and Android
🤖 AI Engine	Python FastAPI	Prediction endpoint + training pipeline (scikit‑learn, TensorFlow)
🔐 Auth	Role‑Based	Farmer / Admin roles with JWT authentication
🗺️ Multi‑Farm	Zone Management	Divide farms into zones with independent schedules
🚨 Alerts	Push Notifications	Real‑time alerts for dry soil, low battery, system faults
🔄 Greywater Ready	Safe Reuse	Architecture supports treated greywater integration
🐳 One‑Command Deploy	Docker Compose	Spin up the entire stack with docker compose up

---

🏗 Architecture

flowchart TD
    subgraph Field["Field Layer"]
        direction TB
        S["Soil Moisture Sensor<br/>ESP32 + Capacitive"]
        V["Solenoid Valve"]
        P["Solar Panel + Battery"]
    end

    subgraph Edge["Edge Layer"]
        direction TB
        F["ESP32 Firmware<br/>Arduino / PlatformIO"]
        FL["Fuzzy Logic<br/>Local Control"]
        M["MQTT Broker<br/>Mosquitto"]
    end

    subgraph Server["Server Layer"]
        direction TB
        API["Express API<br/>Node.js + Prisma"]
        AI["AI Engine<br/>Python / FastAPI"]
        DB[("PostgreSQL")]
        RD[("Redis")]
    end

    subgraph Client["Client Layer"]
        direction TB
        WEB["Web Dashboard<br/>React + Vite"]
        MOBILE["Mobile App<br/>React Native"]
    end

    P --> S
    P --> F
    S -->|publish| M
    M -->|route| API
    M -->|command| F
    F -->|actuate| V
    S --> FL
    FL -->|override| V
    API -->|persist| DB
    API -->|cache| RD
    API -->|predict| AI
    AI -->|response| API
    API -->|broadcast| WEB
    API -->|broadcast| MOBILE

Loading

---

🚀 Quick Start

1. Prerequisites

node --version   # ≥ 20
pnpm --version   # ≥ 8.6 (npm install -g pnpm)
docker --version # ≥ 24
python --version # ≥ 3.11  (for AI engine)

2. Clone and Install

git clone https://github.com/kawacukennedy/hydro_orbit.git
cd hydro_orbit
pnpm install

3. Start Infrastructure (PostgreSQL, Redis, MQTT)

docker compose up -d postgres redis mosquitto

4. Run Database Migrations

pnpm --filter @hydro-orbit/api db:migrate

5. Launch Everything

pnpm dev

Service	URL
Web Dashboard	http://localhost:5173
API Server	http://localhost:3000/api
AI Engine	http://localhost:8000/health
Mobile App	npx expo start → scan QR

---

🛠 Tech Stack

Layer	Technology
Monorepo	Turborepo + pnpm 8
Frontend	React 18, Vite 5, TypeScript, Tailwind CSS 3
Mobile	React Native 0.72, Expo 49
Backend	Node.js 20, Express 4, TypeScript, Prisma ORM
Database	PostgreSQL 15, Redis 7
Messaging	MQTT (Mosquitto), Socket.IO
AI/ML	Python 3.11, FastAPI, scikit‑learn, TensorFlow
Firmware	ESP32, PlatformIO, Arduino Framework
Auth	JWT, bcrypt, role‑based access control
Infrastructure	Docker Compose, GitHub Actions

---

🗺 Roadmap

gantt
    title Hydro-Orbit Roadmap
    dateFormat  YYYY-MM
    section Core
    MVP (current)          :done, 2025-09, 2026-03
    Real sensor integration :active, 2026-03, 2026-07
    Production hardening    :        2026-07, 2026-10
    section AI
    LSTM training pipeline  :active, 2026-03, 2026-06
    Weather API integration :        2026-06, 2026-09
    section Community
    Hardware BOM v1         :active, 2026-03, 2026-05
    Deployment guide        :        2026-05, 2026-07
    Workshop tutorials      :        2026-07, 2026-09

Loading

Upcoming Milestones

• Q2 2026 — Real sensor hardware validation, LSTM training pipeline, weather forecast integration
• Q3 2026 — Production hardening, comprehensive deployment guide, community workshop materials
• Q4 2026 — Mobile app release on App Store / Play Store, hardware kit BOM v2, multi‑language UI

---

👥 Contributing

We welcome contributions of all kinds! See CONTRIBUTING.md for:

• Development setup and coding standards
• Pull request process and commit conventions
• Testing guidelines

Please read our Code of Conduct before participating.

Looking for ways to help?

• 🐛 Report bugs — Open an issue
• 💡 Suggest features — Start a discussion
• 📝 Improve docs — Fix typos, add examples, translate
• 🔧 Write firmware — Help with ESP32 sensor drivers
• 🤖 Train AI models — Contribute to the prediction pipeline
• 🌍 Translate — Help localize the dashboard and docs

---

📚 Documentation

Document	Description
Architecture Overview	System design, data flow, component interaction
API Reference	REST endpoints, WebSocket events, request/response schemas
Deployment Guide	Self‑hosting, Docker, cloud deployment
Simulation Engine	How the simulation generates realistic sensor data
Firmware Guide	ESP32 setup, sensor wiring, calibration

---

🧪 Testing

# Run all tests across the monorepo
pnpm test

# Test specific packages
pnpm --filter @hydro-orbit/shared-utils test
pnpm --filter @hydro-orbit/shared-validators test

# Run API integration tests
pnpm --filter @hydro-orbit/api test

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

_{Built with ❤️ for smallholder farmers — because water is life.
Report Bug • Request Feature • Ask a Question}