Open-source agricultural OS,offline-first,AGPL, grow tent to 500-warehouse scale

An open-source agricultural operating system called gr33n has shipped its Guardian agent layer and crop intelligence modules, enabling offline-first farm management from a single grow tent to 500-warehouse scale. The AGPL-licensed system uses PostgreSQL schemas, Go APIs, Vue dashboards, and Raspberry Pi clients to operate without permanent internet connections or third-party servers. The project aims to reclaim farmer data sovereignty from big agriculture and cloud landlords by providing decentralized tools that work on solar power or mesh networks.

An open-source agricultural operating system designed to reclaim data, land, and autonomy. Current focus: Phase 29 — Guardian agent layer is shipped on main plan /dgang0404/gr33n/blob/main/docs/plans/phase 29 guardian agent layer.md : global slide-out drawer, rule-assisted propose→confirm for alert ack/read, audit + RBAC, contextual Ask Guardian entry points, demo seed alerts, and OpenAPI 0.4.0 . Phase 28 — crop intelligence & Guardian depth is also shipped plan /dgang0404/gr33n/blob/main/docs/plans/phase 28 crop intelligence guardian depth.md . Phase 30 Guardian change-request PR queue — config + Pi via confirm is the natural next slice — plan /dgang0404/gr33n/blob/main/docs/plans/phase 30 guardian change requests.plan.md . Pi / edge field validation Phase 31 remains a parallel activity: real Pi or MQTT bridge with PI API KEY , base64-decode config from GET /farms/{id}/devices , then confirm readings and actuator events , /dgang0404/gr33n/blob/main/pi client/gr33n client.py pi client/gr33n client.py , /dgang0404/gr33n/blob/main/docs/pi-integration-guide.md docs/pi-integration-guide.md . Key playbooks: /dgang0404/gr33n/blob/main/cmd/api/smoke pi contract test.go cmd/api/smoke pi contract test.go , /dgang0404/gr33n/blob/main/docs/workflow-guide.md docs/workflow-guide.md , /dgang0404/gr33n/blob/main/docs/farm-guardian-architecture.md docs/farm-guardian-architecture.md , /dgang0404/gr33n/blob/main/docs/mqtt-edge-operator-playbook.md docs/mqtt-edge-operator-playbook.md , /dgang0404/gr33n/blob/main/docs/farm-guardian-ollama-setup.md docs/farm-guardian-ollama-setup.md , /dgang0404/gr33n/blob/main/docs/local-operator-bootstrap.md docs/local-operator-bootstrap.md , /dgang0404/gr33n/blob/main/docs/insert-commons-pipeline-runbook.md docs/insert-commons-pipeline-runbook.md , /dgang0404/gr33n/blob/main/docs/insert-commons-receiver-playbook.md docs/insert-commons-receiver-playbook.md , /dgang0404/gr33n/blob/main/docs/notifications-operator-playbook.md docs/notifications-operator-playbook.md , /dgang0404/gr33n/blob/main/docs/domain-modules-operator-playbook.md docs/domain-modules-operator-playbook.md , /dgang0404/gr33n/blob/main/docs/mobile-distribution.md docs/mobile-distribution.md , /dgang0404/gr33n/blob/main/docs/audit-events-operator-playbook.md docs/audit-events-operator-playbook.md , /dgang0404/gr33n/blob/main/docs/terminology-guideline.md docs/terminology-guideline.md , /dgang0404/gr33n/blob/main/docs/phase-13-operator-documentation.md docs/phase-13-operator-documentation.md . /dgang0404/gr33n/blob/main/docs/phase-14-operator-documentation.md docs/phase-14-operator-documentation.md gr33n is a modular, scalable, and decentralized farm management system built for real humans — not cloud landlords. Whether you're managing a homestead on solar or automating thousands of acres, gr33n adapts to your size, ethics, and bandwidth. It's PostgreSQL schemas + Go APIs + Vue dashboards + Raspberry Pi clients + shared insert statements. But more than that: it's a political stance in schema form. "If your DNA, soil, labor, and climate data feed trillion-dollar industries — and you're not seeing a dime — that's not tech, that's extraction." This project exists because: - Big Ag is closing the loop on food systems, and we're cracking it back open. - Data rights matter — even your soil and sunlight deserve consent. - Billionaires shouldn't profit off your greenhouse or genome without giving back. - Farmers, tinkerers, and off-gridders deserve tools that don't call home. gr33n will never require a permanent internet connection, forced login, or hidden check-in with third-party servers. Whether you're on an island, a mountaintop, or a mesh-netted greenhouse, gr33n works where you live, without compromise. - Modularity — Each ag domain crops, animals, natural-farming inputs, IoT sensors lives in its own schema. Use what you need, prune the rest. Enable modules per-farm via gr33ncore.farm active modules . - Connectivity Optional — Works offline, intranet-only, or online. Supports Supabase or bare-metal Postgres with TimescaleDB/PostGIS. - Automation-Ready — Schedule tasks, trigger actuators, run AI models — or run it all manually. Your tech, your tempo. - Insert Commons farm-side sender — Per-farm opt-in in Settings; POST /farms/{id}/insert-commons/sync builds coarse, pseudonymous aggregates and optionally POSTs them to INSERT COMMONS INGEST URL with optional Authorization: Bearer <INSERT COMMONS SHARED SECRET . Sync attempts are persisted GET /farms/{id}/insert-commons/sync-events with idempotency keys , rate limits , and server-side backoff after repeated delivery failures. A separate farm audit trail records sensitive actions membership, opt-in, sync attempts, finance COA changes, cost exports, receipt access, and more for owner/manager review via GET /farms/{id}/audit-events see . For self-hosted pilots, an optional docs/audit-events-operator-playbook.md receiver process cmd/insert-commons-receiver , make run-receiver validates payloads, enforces the shared secret, dedupes on payload hash, and stores rows in Postgres — seeand migration docs/insert-commons-receiver-playbook.md db/migrations/20260417 phase13 insert commons receiver.sql . Apply db/migrations/20260415 phase11 rbac receipts commons.sql and db/migrations/20260416 phase12 insert commons federation.sql on existing databases. Custom clients POSTing ingest JSON themselves must use the exact documented shape only six top-level keys, complete aggregates children, boolean includes pii or validation returns 400 — see docs/insert-commons-pipeline-runbook.md Custom senders . | Layer | Technology | |---|---| | API | Go 1.25 · net/http stdlib | | Database | PostgreSQL 14+ · TimescaleDB · PostGIS | | Query layer | sqlc generated — do not edit internal/db/ | | Frontend | Vue 3 · Vite · Pinia · Tailwind CSS | | Pi client | Python 3 · RPi.GPIO / smbus2 | | Auth | Supabase hosted / local peer auth dev | | Schema | Multi-schema PostgreSQL — gr33ncore + gr33nnaturalfarming | gr33n/ ├── scripts/ │ ├── bootstrap-local.sh Schema, migrations, npm ci, .env from example │ ├── setup-first-clone.sh First clone + optional --install-system-deps │ ├── install-system-deps-debian.sh Debian/Ubuntu: sudo apt Postgres+Node not Go │ └── install-pi-edge-deps.sh Raspberry Pi OS: sudo apt for pi client + optional Docker ├── cmd/api/ │ ├── main.go Entry point, DB pool, server startup │ ├── routes.go All HTTP route registrations │ └── cors.go CORS middleware ├── cmd/insert-commons-receiver/ │ └── main.go Optional pilot ingest service for Insert Commons POST /v1/ingest , GET /v1/stats ├── internal/ │ ├── db/ sqlc-generated query layer DO NOT EDIT │ ├── handler/ │ │ ├── farm/ GET /farms/:id │ │ ├── zone/ Zones CRUD │ │ ├── sensor/ Sensors CRUD + readings endpoints │ │ ├── device/ Devices CRUD + status toggle │ │ └── task/ Tasks list + status update │ ├── httputil/ WriteJSON / WriteError helpers │ ├── insertcommonsreceiver/ Optional Insert Commons ingest HTTP handler │ └── platform/ │ └── commontypes/ Shared enum types for sqlc ├── db/ │ ├── schema/ │ │ └── gr33n-schema-v2-FINAL.sql Full PostgreSQL schema source of truth │ ├── seeds/ │ │ └── master seed.sql Demo farm: natural-farming inventory + JADAM-style inputs v1.005 │ └── queries/ sqlc SQL source files ├── ui/ Vue 3 frontend │ └── src/ │ ├── views/ Dashboard, Zones, Sensors, Actuators, Schedules, Inventory │ ├── stores/farm.js Pinia store — all API state │ ├── api/index.js Axios instance → localhost:8080 │ └── router/index.js Vue Router ├── pi client/ │ ├── gr33n client.py Sensor daemon — reads GPIO, POSTs readings to API │ ├── config.yaml Per-node hardware mapping │ ├── gr33n.service systemd unit for autostart │ └── setup.sh One-time Pi bootstrap ├── sqlc.yaml ├── go.mod / go.sum ├── openapi.yaml Full API spec paste into editor.swagger.io for live UI ├── INSTALL.md ├── ARCHITECTURE.md └── SECURITY.md First time after git clone: run or ./scripts/setup-first-clone.sh — it pulls Go deps, creates make first-clone .env / ui/.env from examples, runs to load schema and scripts/bootstrap-local.sh npm ci in ui/ . On Debian/Ubuntu , ./scripts/setup-first-clone.sh --install-system-deps make first-clone-install-deps runs first Postgres 16 + extensions + Node 22; Go still from sudo apt go.dev/dl https://go.dev/dl/ . Otherwise you must have Postgres with TimescaleDB, PostGIS, and pgvector available first native , or use for the Compose database. Step-by-step: ./scripts/setup-first-clone.sh --docker docs/local-operator-bootstrap.md /dgang0404/gr33n/blob/main/docs/local-operator-bootstrap.md . How the database is actually defined ignore stale ERDs : docs/database-schema-overview.md /dgang0404/gr33n/blob/main/docs/database-schema-overview.md . Full setup in INSTALL.md /dgang0404/gr33n/blob/main/INSTALL.md . Short manual version: 1. Clone git clone https://github.com/dgang0404/gr33n.git cd gr33n 2. Create and migrate the database sudo -u postgres psql -c "CREATE DATABASE gr33n;" psql -d gr33n -f db/schema/gr33n-schema-v2-FINAL.sql 3. Seed demo data natural farming + JADAM-style starter labels psql -d gr33n -f db/seeds/master seed.sql 4. Run the API from repo root cp .env.example .env once: edit .env with DATABASE URL, JWT SECRET, PI API KEY if using auth Or only: export DATABASE URL="postgres://$ whoami @/gr33n?host=/var/run/postgresql" go run -tags dev ./cmd/api/ 5. Run the frontend separate terminal cd ui && npm install && npm run dev API → http://localhost:8080 UI → http://localhost:5173 You do not need to re-clone or re-seed every time. From the repo root: make restart-local-serve starts Postgres Compose , waits, sanity-checks, then API + UI Or step by step: make restart-local Postgres only + db sanity report make dev-auth-test API + UI in separate jobs JWT login like production Details: docs/local-operator-bootstrap.md /dgang0404/gr33n/blob/main/docs/local-operator-bootstrap.md after-a-reboot-same-db-volume--no-full-reinstall . First cold go run after reboot can take several minutes — pre-build with go build -tags dev -o ./bin/api ./cmd/api/ if you want faster restarts.Receipt storage defaults to local disk for development: FILE STORAGE BACKEND=local FILE STORAGE DIR=./data/files Production deployments can switch receipts to S3-compatible object storage by setting: FILE STORAGE BACKEND=s3 S3 BUCKET=<bucket S3 REGION=<region - optional: S3 ENDPOINT=<custom endpoint for MinIO / R2 / other S3-compatible providers - optional: S3 PREFIX=<key prefix - optional: S3 ACCESS KEY ID and S3 SECRET ACCESS KEY - optional: S3 USE PATH STYLE=true - optional: S3 DISABLE HTTPS=true for local/test endpoints only - optional: FILE STORAGE SIGNED URL TTL SECONDS=300 for short-lived receipt download links To backfill existing blobs from an old local FILE STORAGE DIR into the configured target backend before cutover: 1. Keep DATABASE URL pointed at the live DB 2. Point the target backend env vars at the new storage location 3. Run a dry run first go run ./cmd/filebackfill --source-dir /path/to/old/files --dry-run 4. Then copy all attachments or only receipts go run ./cmd/filebackfill --source-dir /path/to/old/files go run ./cmd/filebackfill --source-dir /path/to/old/files --file-type cost receipt The backfill preserves each attachment's existing storage path , so DB rows do not change. After the copy is complete, switch the API to the new FILE STORAGE BACKEND and verify a few receipt downloads before removing the old local storage. For operator guidance on receipt storage cutover plus DB/blob backup and restore, see docs/receipt-storage-cutover-runbook.md . Phase 12 adds an offline write queue for the Tasks workflow create task and advance status : - when offline or on retryable network failure , task writes are queued locally - queued items are marked in the Tasks UI - each queued item can be retried or discarded - queued writes auto-sync on reconnect, and manual Sync now is available - non-retryable server failures are shown as stale/conflict items for operator review Install/offline notes: - install the app from your browser for field use PWA - keep one online sync checkpoint before long offline sessions - after reconnect, verify queued writes drained before ending a shift For Play Store / App Store / MDM distribution without replacing the PWA, use the optional Capacitor scaffold in ui/ npm run build:cap , cap:sync , platform add/open . See docs/mobile-distribution.md /dgang0404/gr33n/blob/main/docs/mobile-distribution.md . Base URL: http://localhost:8080 — authoritative request/response schemas in openapi.yaml /dgang0404/gr33n/blob/main/openapi.yaml . Path placeholders use :id , :rid , :uid , :iid for readability the server matches the same paths with {id} style . | Method | Path | Description | |---|---|---| | GET | /health | API + DB health check | | POST | /auth/login | Authenticate & receive JWT | | POST | /auth/register | Register a new account or set password for an invited user existing email with no password yet | | GET | /auth/mode | Current auth mode dev / production / auth test | | GET | /capabilities | Feature flags — {"ai enabled": bool} . Read by the UI at startup to gate Farm Guardian / Knowledge Ask-LLM. | Header: X-API-Key: <PI API KEY see env configuration for the API process . | Method | Path | Description | |---|---|---| | POST | /sensors/:id/readings | Pi posts a sensor reading | | PATCH | /devices/:id/status | Pi heartbeat / status update | | POST | /actuators/:id/events | Pi reports executed command | | DELETE | /devices/:id/pending-command | Pi clears pending command after execution | Farm API POSTs JSON to INSERT COMMONS INGEST URL ; this repo’s pilot receiver go run ./cmd/insert-commons-receiver/ or make run-receiver listens on INSERT COMMONS RECEIVER LISTEN default :8765 and implements: | Method | Path | Description | |---|---|---| | GET | /health | Process liveness | | GET | /v1/stats | Pilot aggregate counts pseudonyms, daily ingests, retention — same Bearer auth as ingest | | POST | /v1/ingest | Validate payload, optional Authorization: Bearer <INSERT COMMONS SHARED SECRET , optional Gr33n-Idempotency-Key forwarded from farm sync , persist idempotently | Details, migration, and retention: docs/insert-commons-receiver-playbook.md /dgang0404/gr33n/blob/main/docs/insert-commons-receiver-playbook.md . If you build or forward JSON manually, match the farm API’s ingest schema no extra top-level fields; full aggregates ; privacy.includes pii as JSON boolean ; GET /farms/:id/insert-commons/preview returns a valid example body — full rules in . /dgang0404/gr33n/blob/main/docs/insert-commons-pipeline-runbook.md docs/insert-commons-pipeline-runbook.md Header: Authorization: Bearer <JWT SSE also supports ?token= on the stream URL where documented . Farm access: most /farms/:id/... routes require the user to be the farm owner or a member gr33ncore.farm memberships . Role caps apply per area for example view vs edit costs, operate for field workflows, admin for farm settings and membership . Exact checks live in internal/farmauthz and in openapi.yaml /dgang0404/gr33n/blob/main/openapi.yaml per route. Integration tests under cmd/api/ TestMain in cmd/api/smoke test.go /dgang0404/gr33n/blob/main/cmd/api/smoke test.go spin up an httptest server with and a real JWT login flow. They need AUTH MODE=auth test Postgres at schema + migrations; DATABASE URL master seed recommended . Env, CI behavior, and data-dependent skips: . /dgang0404/gr33n/blob/main/docs/local-operator-bootstrap.md api-integration-smoke-tests docs/local-operator-bootstrap.md | Method | Path | Description | |---|---|---| | PATCH | /auth/password | Change password must be logged in | | GET | /profile | Current user profile | | PUT | /profile | Update current user profile | | GET | /units | List all measurement units | | Method | Path | Description | |---|---|---| | GET | /farms | List farms; use ?user id=<uuid to restrict to that user’s farms recommended for UIs . If omitted, lists all farms — use only in trusted operator contexts. | | POST | /farms | Create farm | | GET | /farms/:id | Farm detail member or owner | | PUT | /farms/:id | Update farm record admin: owner or manager | | DELETE | /farms/:id | Soft-delete farm admin | | Method | Path | Description | |---|---|---| | GET | /farms/:id/members | List members and roles | | POST | /farms/:id/members | Invite or add member email , role in farm , optional full name | | PATCH | /farms/:id/members/:uid/role | Change member role :uid = user UUID | | DELETE | /farms/:id/members/:uid | Remove member from farm | | Method | Path | Description | |---|---|---| | PATCH | /farms/:id/insert-commons/opt-in | Toggle Insert Commons aggregate sharing admin | | GET | /farms/:id/insert-commons/preview | Preview validated ingest JSON only — no sync, no history admin | | POST | /farms/:id/insert-commons/sync | Build aggregates and POST to INSERT COMMONS INGEST URL when set admin or finance | | GET | /farms/:id/insert-commons/sync-events | Paginated sync attempt history admin or finance / anyone with cost view | | GET | /farms/:id/audit-events | Sensitive-action audit log admin only; query limit , offset | | Method | Path | Description | |---|---|---| | GET | /farms/:id/zones | List zones for farm | | GET | /zones/:id | Zone detail | | POST | /farms/:id/zones | Create zone | | PUT | /zones/:id | Update zone | | DELETE | /zones/:id | Delete zone | | Method | Path | Description | |---|---|---| | GET | /farms/:id/devices | List devices | | GET | /devices/:id | Device detail | | POST | /farms/:id/devices | Create device | | DELETE | /devices/:id | Delete device | | GET | /farms/:id/actuators | List actuators for farm | | PATCH | /actuators/:id/state | Update actuator state dashboard | | GET | /actuators/:id/events | Actuator event history | | Method | Path | Description | |---|---|---| | GET | /farms/:id/sensors | List sensors | | GET | /farms/:id/sensors/stream | SSE live sensor readings JWT may be passed as query token | | GET | /sensors/:id | Sensor detail | | POST | /farms/:id/sensors | Create sensor | | DELETE | /sensors/:id | Delete sensor | | GET | /sensors/:id/readings/latest | Latest reading | | GET | /sensors/:id/readings | List readings since , until , limit , … | | GET | /sensors/:id/readings/stats | Aggregate stats for a time range | | Method | Path | Description | |---|---|---| | GET | /farms/:id/schedules | List schedules | | PATCH | /schedules/:id/active | Toggle schedule active | | GET | /farms/:id/automation/runs | List automation runs for farm | | GET | /schedules/:id/actuator-events | Actuator events triggered by schedule | | GET | /automation/worker/health | Automation worker health | | Method | Path | Description | |---|---|---| | GET | /farms/:id/tasks | List tasks | | POST | /farms/:id/tasks | Create task | | PATCH | /tasks/:id/status | Update task status | | Method | Path | Description | |---|---|---| | GET | /farms/:id/fertigation/reservoirs | List reservoirs | | POST | /farms/:id/fertigation/reservoirs | Create reservoir | | PATCH | /fertigation/reservoirs/:rid | Update reservoir | | DELETE | /fertigation/reservoirs/:rid | Delete reservoir | | GET | /farms/:id/fertigation/ec-targets | List EC targets | | POST | /farms/:id/fertigation/ec-targets | Create EC target | | GET | /farms/:id/fertigation/programs | List programs | | POST | /farms/:id/fertigation/programs | Create program | | PATCH | /fertigation/programs/:rid | Update program | | DELETE | /fertigation/programs/:rid | Delete program | | GET | /farms/:id/fertigation/events | List fertigation events ?crop cycle id= optional | | POST | /farms/:id/fertigation/events | Create fertigation event optional crop cycle id | | Method | Path | Description | |---|---|---| | GET | /farms/:id/crop-cycles | List crop cycles | | POST | /farms/:id/crop-cycles | Create crop cycle | | GET | /crop-cycles/:id | Get crop cycle | | PUT | /crop-cycles/:id | Update crop cycle | | DELETE | /crop-cycles/:id | Deactivate crop cycle | | PATCH | /crop-cycles/:id/stage | Update growth stage | | Method | Path | Description | |---|---|---| | GET | /farms/:id/costs/summary | Cost totals income, expenses, net | | GET | /farms/:id/costs | List cost transactions limit , offset , … | | GET | /farms/:id/costs/export | Download CSV format=csv or format=gl csv | | GET | /farms/:id/finance/coa-mappings | List COA mappings for GL export | | PUT | /farms/:id/finance/coa-mappings | Save COA mapping overrides | | DELETE | /farms/:id/finance/coa-mappings | Reset all COA overrides | | DELETE | /farms/:id/finance/coa-mappings/:category | Reset one category override | | POST | /farms/:id/costs | Create cost transaction | | PUT | /costs/:id | Update cost transaction | | DELETE | /costs/:id | Delete cost transaction | | POST | /farms/:id/cost-receipts | Upload cost receipt multipart: file , optional cost transaction id | | GET | /file-attachments/:id/content | Inline file bytes cost receipt when linked | | GET | /file-attachments/:id/download | Presigned or proxied download URL JSON backend-dependent | | Method | Path | Description | |---|---|---| | GET | /farms/:id/alerts | List alerts for farm | | GET | /farms/:id/alerts/unread-count | Unread count | | PATCH | /alerts/:id/read | Mark alert read | | PATCH | /alerts/:id/acknowledge | Acknowledge alert | AI ENABLED=true required; LLM BASE URL + LLM MODEL required for the chat endpoint. POST /v1/chat returns 503 in Lite mode and 429 when rolling-window cost guards fire CHAT COST MAX TOKENS PER USER / CHAT COST MAX TOKENS PER FARM . | Method | Path | Description | |---|---|---| | POST | /v1/chat | Send a message to Farm Guardian. Optional farm id → RAG grounding + live snapshot. Optional session id UUID for multi-turn context replay. Optional "stream": true for SSE streaming. Response includes answer , grounded , citations , session id , turn index , prompt tokens , completion tokens . | | GET | /v1/chat/sessions | List recent conversation sessions up to 50, latest-first . | | GET | /v1/chat/sessions/:id | Full ordered turn history for a session. | | PATCH | /v1/chat/sessions/:id | Rename session {"title": "..."} , empty string clears . | | DELETE | /v1/chat/sessions/:id | Delete session and all its turns. | | GET | /v1/chat/usage | Rolling-window token budget dashboard per-user; optional ?farm id= for per-farm . Settings → Guardian usage card. | | Method | Path | Description | |---|---|---| | GET | /crop-cycles/:id/summary | Per-cycle fertigation + cost + yield + stage history JSON . | | GET | /crop-cycles/:id/summary.csv | Same data, flat CSV row. | | GET | /farms/:id/crop-cycles/compare?ids=1,2,3 | Side-by-side compare up to 5 cycles . | | GET | /farms/:id/crop-cycles/compare.csv | Compare as CSV one row per cycle . | pgvector + embeddings required for search; AI ENABLED=true + LLM configured required for answer synthesis. | Method | Path | Description | |---|---|---| | POST | /farms/:id/rag/search | Semantic nearest-neighbour search over farm knowledge chunks. | | POST | /farms/:id/rag/answer | Retrieve top-K chunks then synthesise an LLM answer Lite mode: 503 for synthesis; search still works . | | Method | Path | Description | |---|---|---| | GET | /farms/:id/naturalfarming/inputs | List input definitions | | POST | /farms/:id/naturalfarming/inputs | Create input definition | | PUT | /naturalfarming/inputs/:id | Update input definition | | DELETE | /naturalfarming/inputs/:id | Delete input definition | | GET | /farms/:id/naturalfarming/batches | List input batches | | POST | /farms/:id/naturalfarming/batches | Create input batch | | PUT | /naturalfarming/batches/:id | Update input batch | | DELETE | /naturalfarming/batches/:id | Delete input batch | | Method | Path | Description | |---|---|---| | GET | /farms/:id/naturalfarming/recipes | List application recipes | | POST | /farms/:id/naturalfarming/recipes | Create recipe | | GET | /naturalfarming/recipes/:id | Get recipe | | PUT | /naturalfarming/recipes/:id | Update recipe | | DELETE | /naturalfarming/recipes/:id | Delete recipe | | GET | /naturalfarming/recipes/:id/components | List recipe components | | POST | /naturalfarming/recipes/:id/components | Add component | | DELETE | /naturalfarming/recipes/:id/components/:iid | Remove component :iid = component row id | The master seed loads a demo farm farm id = 1 , gr33n Demo Farm with natural-farming inventory and JADAM -style input names JMS, JLF, … , photoperiod schedules, fertigation events, crop cycles, and automation — verified clean against the live schema: | Table | Rows | Contents | |---|---|---| farms | 1 | gr33n Demo Farm | zones | 3 | Veg Room, Flower Room, Outdoor Garden | crop cycles | 3 | Veg canopy 18/6 , Flower run 12/12 , Outdoor raised beds | sensors | 10 | PAR, lux, temp, humidity, EC, pH, CO2, soil moisture | input definitions | 15 | JMS, LAB, FPJ, FFJ, OHN, JHS, WCA, WCS, JWA, JS, JLF variants, compost tea | application recipes | 14 | Soil drenches, foliar sprays, pest control, fungicide | recipe components | 20 | Input-to-recipe links with dilution ratios | schedules | 14 | Light 24/0, 18/6, 16/8, 12/12 + watering programs per grow stage | automation rules | 7 | Automated light on/off rules per grow stage | Apply once: make seed or psql -d gr33n -f db/seeds/master seed.sql . Farm Guardian needs a RAG corpus too. The seed loads operational rows zones, cycles, NF inputs, … but does not pre-populate gr33ncore.rag embedding chunks . After seeding, run make rag-ingest-demo or for wipe + seed + ingest : make dev-stack-fresh-rag make rag-ingest-demo needs EMBEDDING API KEY in .env; skips cleanly if unset or one-shot fresh demo with embeddings: make dev-stack-fresh-rag See docs/farm-guardian-architecture.md /dgang0404/gr33n/blob/main/docs/farm-guardian-architecture.md for the three knowledge layers Llama weights + RAG corpus + live snapshot . Smoke-test pollution: Running make test against a long-lived dev DB accumulates junk rows. For a clean Guardian demo, use make dev-stack-fresh or . For day-to-day migration updates on an existing DB, make dev-stack-fresh-rag is idempotent. make dev-stack make help Show all targets make bootstrap-local Guided DB + env + UI deps see docs/local-operator-bootstrap.md make bootstrap-local-docker Same, but start stack with docker compose make compose-db-up Postgres only — docker-compose db Timescale + pgvector ; pair .env DATABASE URL with INSTALL.md §2 / .env.example make dev-stack Idempotent: migrations + seed on existing DB auto-skips schema make dev-stack-fresh Wipe Compose volume + full bootstrap + seed clean Guardian demo make dev-stack-fresh-rag Same + rag-ingest demo farm when EMBEDDING API KEY is set make rag-ingest-demo Index farm id=1 only skip message if no embedding key make local-up dev-stack then API + UI same as ./scripts/dev-stack.sh --serve make restart-local After reboot: Compose db + wait + sanity report no migrations make restart-local-serve restart-local then API + UI make dev-auth-test make check-stack Verify DATABASE URL + pgvector + optional API /health see docs/local-operator-bootstrap.md make run Run the API server make run-receiver Run optional Insert Commons receiver see docs/insert-commons-receiver-playbook.md make dev Run API + UI dev server in parallel make ui Run the Vue dev server make build Build the Go binary make build-ui Build the Vue frontend for production make test Run Go tests -tags dev, ./... make lint Run go vet -tags dev, ./... make audit-openapi OpenAPI ↔ cmd/api/routes.go shell diff + Go parity test in cmd/api/openapi parity test.go make sqlc Regenerate sqlc Go code from SQL queries make seed Apply seed data to the database make schema Apply the schema to the database make up Start Docker Compose services make down Stop Docker Compose services make logs Tail Docker Compose logs make clean Remove build artifacts Phase 23 / pre-merge gate local : make test , make lint , make audit-openapi , python3 -m pytest pi client/test gr33n client.py pi client/test mqtt telemetry bridge.py -q , and npm --prefix ui run build . make test expects a reachable see DATABASE URL bootstrap — smoke tests /dgang0404/gr33n/blob/main/docs/local-operator-bootstrap.md api-integration-smoke-tests so cmd/api integration tests actually run.The Pi daemon runs four threads concurrently: sensor-loop — reads each GPIO/I2C sensor at its configured interval, POSTs to POST /sensors/:id/readings heartbeat-loop — PATCHes device status every 30s so the dashboard shows "online" schedule-loop — polls GET /farms/:id/devices for pending command in device config JSONB, executes via GPIO, reports via POST /actuators/:id/events , then clears via DELETE /devices/:id/pending-command flush-loop — drains the offline SQLite queue when API becomes reachable Configure sensors, actuators with device id , and GPIO pins in pi client/config.yaml . Install as a systemd service with pi client/setup.sh so it starts automatically on boot. Deployments: Edge-only Pis vs running Postgres + API + UI on the Pi , and how setups scale to split DB/API/UI — see . Minimal Pi OS apt packages before docs/raspberry-pi-and-deployment-topology.md setup.sh : ./scripts/install-pi-edge-deps.sh make install-pi-edge-deps .MCUs can publish to an on-farm MQTT broker ; a bridge process subscribes and forwards to POST /sensors/readings/batch using X-API-Key same server PI API KEY as the Pi daemon . Reference implementation: . Topics, TLS, ACLs, and tasking: /dgang0404/gr33n/blob/main/pi client/mqtt telemetry bridge.py pi client/mqtt telemetry bridge.py . /dgang0404/gr33n/blob/main/docs/mqtt-edge-operator-playbook.md docs/mqtt-edge-operator-playbook.md gr33n's AI layer runs fully on your intranet — no data leaves the LAN in Full mode. Knowledge is never sent to cloud APIs. Farm Guardian Phase 27 is a conversational assistant powered by Llama 3.1 70B Q4 running on an on-premise GPU box via Ollama https://ollama.ai . It layers three knowledge sources: Llama weights — general agricultural, scientific, and world knowledge baked in during training. Your farm's RAG corpus — anything you've ingested into POST /farms/{id}/rag/ingest sensor notes, crop logs, manuals, etc. retrieved at query time via pgvector similarity search. Live farm-state snapshot — zones, active crop cycles, and unread alerts pulled from the DB at the start of every grounded turn so answers reflect right now , not a stale index. The AI features are gated by AI ENABLED default on and degrade gracefully: in Lite mode no LLM configured POST /v1/chat returns 503 and the "Ask LLM " button in the Knowledge UI is disabled with an explanation. In Full mode , Guardian is available from the global slide-out drawer on any page sidebar, TopBar ✨, right-edge tab and at /chat . What Guardian does today Phase 27–29 : conversational Q&A — explain alerts, compare crop cycles, cite your RAG corpus, and read the live farm snapshot. Phase 29 adds confirmed agent actions : Guardian may propose alert acknowledge or mark read ; the operator taps Confirm on an inline card POST /v1/chat/confirm . Nothing writes without your OK. Viewers can chat but cannot confirm. All confirmed actions log guardian tool executed to the farm audit trail. Guardian does not change schedules, programs, or actuators autonomously — that scope is Phase 30 still Confirm-only . What comes next Phase 30 : expanded PR-queue tools tasks, cycle stage, schedules, Pi actuator enqueue — plan /dgang0404/gr33n/blob/main/docs/plans/phase 30 guardian change requests.plan.md . All AI calls remain inside your farm's intranet: Pi clients ──HTTPS──▶ Go API ├──▶ Postgres + pgvector farm data + RAG corpus └──▶ Ollama Llama 3.1 70B Q4, GPU box on intranet Browser ──HTTPS──▶ Vue UI ──▶ Go API same as Pi See docs/farm-guardian-architecture.md /dgang0404/gr33n/blob/main/docs/farm-guardian-architecture.md for the request flow + three-knowledge-layer breakdown, for install/setup, and /dgang0404/gr33n/blob/main/docs/farm-guardian-ollama-setup.md docs/farm-guardian-ollama-setup.md for all /dgang0404/gr33n/blob/main/INSTALL.md INSTALL.md AI / LLM / CHAT env vars.- AI is modular and never mandatory — AI ENABLED=false produces a clean Lite deployment. - No cloud calls, no training on your data, no opt-in required for basic operation. - Cost guards CHAT COST MAX TOKENS PER USER / PER FARM prevent runaway token usage on shared deployments. A phase-by-phase ledger of what's live on main . Each row links to the governing plan doc where one exists; undated rows predate the phase-plan convention. | Phase | Focus | Status | Links | |---|---|---|---| | 10 | JWT smoke tests, farm-scoped write auth, fertigation ↔ crop cycle link, costs CSV, SensorDetail UX | ✅ Done | — | | 11 | Farm RBAC, cost receipts + local storage, PWA shell, Insert Commons opt-in | ✅ Done | — | | 12 | Insert Commons federation | ✅ Done | db/migrations/20260416 phase12 insert commons federation.sql | | 13 | Platform evolution — receiver, audit/compliance, offline, finance depth, tenancy | ✅ Done | | plan /dgang0404/gr33n/blob/main/docs/plans/phase 14 network and commons.plan.md · ops doc /dgang0404/gr33n/blob/main/docs/phase-14-operator-documentation.md plan /dgang0404/gr33n/blob/main/docs/plans/phase 15 farm onboarding.plan.md plan /dgang0404/gr33n/blob/main/docs/plans/phase 18 platform polish.plan.md plan /dgang0404/gr33n/blob/main/docs/plans/phase 19 safety and alert rules.plan.md plan /dgang0404/gr33n/blob/main/docs/plans/phase 20 automation rule engine.plan.md gr33ncore.zone setpoints + rule engine integration + UI cost transactions.crop cycle id aquaponics.loops , feed autologging, bootstrap upgrade executable actions surface + metadata.steps backfill + ResolveProgramActions fallback plan /dgang0404/gr33n/blob/main/docs/plans/phase 20 95 rag prep and housekeeping.plan.md GET /crop-cycles/{id}/summary , compare, UI, CSV per plan plan /dgang0404/gr33n/blob/main/docs/plans/phase 21 crop cycle analytics.plan.md · Phase 28 /dgang0404/gr33n/blob/main/docs/plans/phase 28 crop intelligence guardian depth.md 22 Worker program-tick + final — metadata.steps backfill sweep runProgramTick dispatches executable actions per program, automation runs.program id attribution, 20260517 sweep + per-program NOTICE log, structured fallback warning 23 Stabilization sprint — CI gates, smoke + DATABASE URL docs, OpenAPI parity, Pi/API key runbook, workflow + MQTT accuracy, worker monitoring docs plan /dgang0404/gr33n/blob/main/docs/plans/phase 23 stabilization sprint.plan.md · exit sign-off /dgang0404/gr33n/blob/main/docs/plans/phase 23 stabilization sprint.plan.md exit-sign-off 24 RAG retrieval system — embeddings + farm-scoped retrieval API + optional LLM synthesis ; builds on 20.95 RAG-prep /dgang0404/gr33n/blob/main/docs/plans/phase 20 95 rag prep and housekeeping.plan.md plan /dgang0404/gr33n/blob/main/docs/plans/phase 24 rag retrieval system.plan.md 25 RAG operations & expansion — ingest breadth, incremental re-embed, CI/pgvector parity, integration tests + synthesis limits, UX/docs schema ERD text /dgang0404/gr33n/blob/main/docs/schema-erd-text.md plan /dgang0404/gr33n/blob/main/docs/plans/phase 25 rag operations and expansion.plan.md 26 Operator tutorial, observability, RAG scope — operator-guide UI, Loki/Promtail/Grafana logging overlay, RAG scope/threat-model, LLM retry/backoff, Ollama setup runbook plan /dgang0404/gr33n/blob/main/docs/plans/phase 26 operator tutorial observability rag.plan.md 27 Farm Guardian AI layer — on-premise Llama 3.1 70B via Ollama, AI ENABLED + /capabilities , streaming POST /v1/chat , multi-turn history + RAG grounding + live farm-state snapshot, session CRUD, token usage, cost guards, /chat UI panel with session sidebar + bulk-delete plan /dgang0404/gr33n/blob/main/docs/plans/phase 27 farm guardian ai layer.md 28 Crop intelligence & Guardian depth — crop-cycle analytics, Guardian ↔ cycles + alerts, token-usage dashboard, 80% budget warnings, OpenAPI 0.3.0 plan /dgang0404/gr33n/blob/main/docs/plans/phase 28 crop intelligence guardian depth.md 29 Guardian agent layer candidate — tool-calling actions with confirmation, global slide-out panel, Guardian-ready bootstrap plan /dgang0404/gr33n/blob/main/docs/plans/phase 29 guardian agent layer.md Stabilization sprint closed on main 2026-04-18 . Criterion-by-criterion table and next-phase links: . docs/plans/phase 23 stabilization sprint.plan.md — Exit sign-off| Gate | Status | |---|---| CI matrix make test , make lint , make audit-openapi ; pytest + UI build — see | ✅ | OpenAPI ↔ routes.go | ✅ | Smoke / DATABASE URL + CI without DB | ✅ Documented + TestMain behavior | | Operator docs workflow, MQTT, Pi auth, automation logs | ✅ | In flight / next up priority order : - Phase 23 — stabilization — done ; exit sign-off /dgang0404/gr33n/blob/main/docs/plans/phase 23 stabilization sprint.plan.md exit-sign-off . - Phase 24 — RAG retrieval — vectors + farm-scoped API + optional LLM synthesis; Knowledge UI. - Phase 25 — RAG operations & expansion — CI parity, ingest breadth, incremental re-embed, limits/tests, docs/UX polish. - Phase 26 — operator tutorial, observability, RAG scope — guide UI, Loki overlay, RAG boundary doc, LLM retry, Ollama runbook. - Phase 27 — Farm Guardian AI layer — streaming chat, multi-turn history, RAG grounding, live snapshot, session management, cost guards. - Pi ↔ API contract pass — smoke tests TestPiContract in: enqueue cmd/api/smoke pi contract test.go pending command → Pi-key GET /farms/1/devices → POST /actuators/{id}/events → DELETE pending. - Phase 28 — crop intelligence & Guardian depth — crop analytics, Guardian snapshot depth, usage dashboard, OpenAPI 0.3.0. - Phase 29 — Guardian agent layer — propose→confirm alert ack/read, slide-out drawer, contextual entry points, OpenAPI 0.4.0 — plan /dgang0404/gr33n/blob/main/docs/plans/phase 29 guardian agent layer.md - Phase 30 — Guardian change requests PR queue — config + actuator proposals, pending inbox, zone photos / optional vision — plan /dgang0404/gr33n/blob/main/docs/plans/phase 30 guardian change requests.plan.md - Phase 31 — field validation & safe edge — Pi/breadboard loop, proves confirmed actuator PRs reach GPIO — plan /dgang0404/gr33n/blob/main/docs/plans/phase 31 field validation and edge.plan.md · enterprise topology sketch /dgang0404/gr33n/blob/main/docs/hypothetical-enterprise-topology.md - Deprecate — after N deploys with zero fallback warnings, promote programs.metadata.steps action source checks to hard errors and drop the column. - Program "run now" API — explicit trigger for unscheduled / ad-hoc programs. - Mobile distribution polish — Capacitor packaging, store submission checklist. - gr33ncore schema — users, sensors, schedules, zones, automation rules - gr33nnaturalfarming schema — inputs, recipes, batches - Go REST API — farms, zones, devices, sensors, tasks, readings - Natural farming demo seed — 15 inputs, 14 recipes, full automation JADAM-style labels - sqlc query layer + enum types - Vue 3 frontend — Dashboard, Zones, Sensors, Actuators, Schedules, Settings, Inventory - Raspberry Pi sensor client with systemd daemon - OpenAPI spec openapi.yaml - Sensor readings live on dashboard SSE stream with JWT query param auth - Phase 10 — JWT smoke tests AUTH MODE=auth test , farm-scoped write authorization, fertigation ↔ crop cycle link, costs CSV export, SensorDetail export UX - Phase 11 — Farm RBAC viewer / operator / finance / manager / owner , cost receipts + local FILE STORAGE DIR storage, PWA-first installable shell manifest + SW in production builds; Capacitor still an option for store-distributed apps , Insert Commons opt-in + early sync hook, OpenAPI updates - Phase 13 — Platform evolution receiver-side Insert Commons, audit/compliance API, offline + finance depth, tenancy experiments, optional Capacitor scaffold; indexes plans and playbooks docs/phase-13-operator-documentation.md - Phase 14 — Field network & commons MQTT/edge, insert pipeline, gr33n inserts catalog, federation/receiver depth, FCM notifications, org governance, domain schema stubs; , docs/plans/phase 14 network and commons.plan.md docs/phase-14-operator-documentation.md - Actuator control pipeline automation worker → pending command → Pi poll → execute → report - Fertigation module — reservoirs, EC targets, programs, events - Natural farming inventory UI — input definitions & batch tracking - Pi heartbeat loop — devices show online/offline in real time - Docker Compose + Dockerfile for containerized deployment - Microcontroller integrations — MQTT → HTTP bridge , pi client/mqtt telemetry bridge.py ; field tasking unchanged docs/mqtt-edge-operator-playbook.md pending command + Pi / bridge poll - Data insert pipeline Insert Commons validation, approval bundles, export — docs/insert-commons-pipeline-runbook.md - LM Studio integration and AI scaffolds for insert-sharing - gr33n inserts — commons catalog API browse + farm import audit; docs/commons-catalog-operator-playbook.md - Stub schemas gr33ncrops , gr33nanimals , gr33naquaponics placeholder tables; enable via farm active modules — docs/domain-modules-operator-playbook.md - Phase 20 — automation rule engine sensor-driven conditions, action dispatch, cooldowns, rule-driven notifications — plan /dgang0404/gr33n/blob/main/docs/plans/phase 20 automation rule engine.plan.md - Phase 20.6–20.9 — stage-scoped setpoints, cost/energy nightly rollups, animal husbandry, labor auto-cost, program actions + metadata.steps backfill - Phase 20.95 — RAG-prep schema housekeeping for AI consumption — plan /dgang0404/gr33n/blob/main/docs/plans/phase 20 95 rag prep and housekeeping.plan.md - Phase 21 — crop cycle analytics & yield summary, compare, UI, CSV — plan /dgang0404/gr33n/blob/main/docs/plans/phase 21 crop cycle analytics.plan.md superseded by Phase 28 WS1 — endpoints shipped - Phase 22 — worker program-tick runProgramTick , automation runs.program id , final metadata.steps backfill sweep, observable fallback warning - Phase 23 — stabilization sprint CI, smoke, OpenAPI parity, docs, small fixes — plan /dgang0404/gr33n/blob/main/docs/plans/phase 23 stabilization sprint.plan.md · exit sign-off /dgang0404/gr33n/blob/main/docs/plans/phase 23 stabilization sprint.plan.md exit-sign-off - Phase 24 — RAG retrieval system vectors + farm-scoped API + optional LLM — plan /dgang0404/gr33n/blob/main/docs/plans/phase 24 rag retrieval system.plan.md - Phase 25 — RAG operations & expansion ingest breadth, incremental re-embed, CI parity, limits, UX/docs — plan /dgang0404/gr33n/blob/main/docs/plans/phase 25 rag operations and expansion.plan.md - Phase 26 — operator tutorial, observability, RAG scope guide UI, Loki overlay, RAG boundary, LLM retry, Ollama runbook — plan /dgang0404/gr33n/blob/main/docs/plans/phase 26 operator tutorial observability rag.plan.md - Phase 27 — Farm Guardian AI layer streaming chat, multi-turn sessions, RAG grounding + live snapshot, cost guards, /chat UI panel — plan /dgang0404/gr33n/blob/main/docs/plans/phase 27 farm guardian ai layer.md - Phase 28 — crop intelligence & Guardian depth crop analytics, Guardian ↔ cycles/alerts, usage dashboard, OpenAPI 0.3.0 — plan /dgang0404/gr33n/blob/main/docs/plans/phase 28 crop intelligence guardian depth.md - Phase 29 — Guardian agent layer propose→confirm, slide-out drawer, Ask Guardian entry points, OpenAPI 0.4.0 — plan /dgang0404/gr33n/blob/main/docs/plans/phase 29 guardian agent layer.md - Phase 30 — Guardian PR queue config agent, actuator proposals, zone vision — plan /dgang0404/gr33n/blob/main/docs/plans/phase 30 guardian change requests.plan.md - Phase 31 — field validation & edge Pi loop, safe actuator, recipe packs — plan /dgang0404/gr33n/blob/main/docs/plans/phase 31 field validation and edge.plan.md · enterprise sketch /dgang0404/gr33n/blob/main/docs/hypothetical-enterprise-topology.md - Fork this repo - Join the insert-sharing network coming soon in gr33n inserts - Help build bridges between sensors, dashboards, and soil - Translate docs, test offline installs, or write a better knf notes parser "Built for the commons." The commons means shared knowledge, shared code, shared resilience. It's an ancient concept — like the village well or a seed bank — remixed into digital space. gr33n lives in this tradition: Free to use, fork, and rebuild. Not fenced off behind corporate toll booths. GNU Affero General Public License v3.0 AGPL-3.0 Use it. Fork it. Share it. If you run it as a service — cloud, SaaS, or otherwise — you must release your modifications back to the community. No exceptions. No toll booths. Just don't try to put a fence around the commons. Built by farmers, hackers, and friends. With sunlight and rage.