A Farm Management Information System with sovereign edge computing — built for a 3-node Raspberry Pi 5 cluster with Hailo-10H AI acceleration, real-time sensor telemetry, and on-device LLM-powered agronomy.

AgriPulse runs entirely on edge hardware: no cloud dependencies, no data leaving the farm. A FastAPI backend orchestrates sensor sampling, actuator control, and AI inference via a local Ollama model, while a lightweight HTML/CSS/JS frontend delivers a responsive dashboard accessible from any browser on the LAN.

• Highlights
• Tech Stack
• Architecture
• Quick Start
  • Prerequisites
  • Option A — Run locally
  • Option B — Docker Compose
  • Option C — Kubernetes
• Configuration
• Pages
• API Reference
• Project Structure
• Hardware Bill of Materials
• Documentation
• Contributing
• Security
• License

Backend

AI / LLM

Frontend

Database

Deployment

Edge Hardware

The frontend ships as vanilla HTML/CSS/JS with no build step and no framework, and real-time communication flows over a single WebSocket (/ws) for telemetry, chat, onboarding, and tool calls.

┌─────────────────────────────────────────────────────────────┐
│                  Frontend (HTML / CSS / JS)                  │
│  Dashboard · Fields · Soil · Plants · Tasks · Irrigation     │
│  Chat · BOM · Setup (AI Onboarding)                          │
└───────────────────────────┬─────────────────────────────────┘
                            │ REST + WebSocket
┌───────────────────────────┴─────────────────────────────────┐
│                FastAPI Backend (Python)                      │
│  Routes · WebSocket Manager · Sensor Manager                 │
│  SQLAlchemy ORM · Ollama Service · Onboarding Service        │
│  Actuator Control                                            │
└─────────────┬───────────────────────────────┬───────────────┘
              │                               │
      ┌───────┴────────┐            ┌─────────┴─────────┐
      │  SQLite /      │            │   Ollama (LLM)    │
      │  PostgreSQL    │            │   llama3.1:8b     │
      └────────────────┘            └───────────────────┘
              │
      ┌───────┴────────────────────────────────────────┐
      │  Edge Hardware (Raspberry Pi 5 cluster)         │
      │  Sensors · Actuators · Hailo NPU · Camera       │
      └─────────────────────────────────────────────────┘

• Python 3.12+
• Ollama running locally with a pulled model (ollama pull llama3.1:8b) — optional; the app falls back to a deterministic parser if Ollama is unreachable.
• pip, and optionally Docker / kubectl for containerized deployment.

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

# 2. (Optional) Start Ollama and pull the model
ollama serve &
ollama pull llama3.1:8b

# 3. Launch the server
uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000

Or use the bundled launcher, which sources .env and prints startup diagnostics:

chmod +x run.sh && ./run.sh

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

Spins up the AgriPulse app alongside an Ollama container:

docker-compose up --build

The app is served on http://localhost:8000; Ollama listens on http://localhost:11434. Persistent volumes are created for both the database and Ollama models.

Note: The first run will download the Llama 3.1 model inside the Ollama container — attach to it and run ollama pull llama3.1:8b, or pre-pull on the host.

Manifests are provided as a Kustomize bundle under k8s/:

kubectl apply -k k8s/

Includes namespace, configmap, deployment, service, ingress, and storage resources.

All settings are read from environment variables (or a .env file at the project root — copy .env.example to get started).

For PostgreSQL, set DATABASE_URL=postgresql://user:password@localhost:5432/agripulse.

All REST endpoints are prefixed with /api/v1.

Connect to ws://host:8000/ws and send JSON frames with an action field:

Inbound message types: data, alert, chat_response, onboard_thought, onboard_template, onboard_error, tool_result.

AgriPulse-EdgeCluster/
├── backend/
│   ├── main.py                # FastAPI app, WebSocket endpoint, actuator tools
│   ├── routes.py              # REST routers (farms, fields, tasks, onboarding, …)
│   ├── models.py              # SQLAlchemy ORM models & Pydantic schemas
│   ├── database.py            # Engine & session factory
│   ├── websocket_manager.py   # Connection manager & WS action dispatch
│   ├── onboarding_service.py  # AI farm-onboarding (Ollama streaming + fallback)
│   ├── ollama_service.py      # AI Architect chat service
│   ├── sensors.py             # Simulated & real sensor managers
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/
│   ├── *.html                 # One page per view (no framework)
│   └── static/
│       ├── css/style.css
│       └── js/{api.js, app.js}
├── k8s/                       # Kubernetes manifests (Kustomize)
├── wiki/                      # Project documentation
├── docker-compose.yml
├── run.sh                     # Local launcher (sources .env)
└── .env.example

• 3× Raspberry Pi 5 (16 GB)
• 1× AI HAT+ Hailo-10H (26 TOPS)
• 1× Sense HAT
• 1× NVMe HAT + 512 GB SSD
• 3× Capacitive Soil Moisture Sensors
• 1× Industrial pH Probe + ADS1115 ADC
• 2× DS18B20 Temperature Sensors
• 1× Global Shutter Camera
• Actuators: pump, mister, solenoid valve, LED grow lights, fans, relay module
• IP65 vented enclosure

See wiki/Hardware-BOM.md for sourcing details.

In-depth guides live in the wiki/ directory:

• Architecture — system design and data flow
• API Reference — detailed endpoint documentation
• WebSocket Protocol — real-time messaging spec
• Frontend Pages — UI tour
• Onboarding — the AI farm-onboarding workflow
• AI Architect — the LLM agronomy assistant
• Hardware BOM — component list & sourcing
• Deployment Guide — local, Docker & Kubernetes
• Kubernetes Deployment — k8s specifics
• Sensor System — real vs. simulated sensors
• Troubleshooting — common issues & fixes

Contributions are welcome. Please read CONTRIBUTING.md for guidelines and CODE_OF_CONDUCT.md for our community standards before opening a pull request.

Found a vulnerability? Please review SECURITY.md for responsible disclosure instructions — do not open a public issue for security-related problems.

Released under the MIT License.