Johgee Open Irrigation

Open-source, AI-native watering advice for UK home gardens.

v1 turns what you already know — garden type, soil, sun, how you water, recent rain and how the soil feels — into an explainable plan: millimetres, litres and runtime. It does not control taps, timers or irrigation hardware. It does not confirm a hosepipe ban for your street.

Numeric recommendations come from a versioned deterministic core. A language model may explain those facts. It must not change millimetres, litres, runtime, restriction status, variant ids or sources.

Status

Public data mode is dynamic after D-01 (2026-08-23): a postcode may use the Met Office DataHub free Global Spot feed, cached by coarse grid. If weather cannot be fetched, the API falls back to manual self-report and never invents millimetres. Restriction status stays unknown; hosepipe and sprinkler advice fail-closed until v3. fixture is test-only.

What you can do today

• Call POST /v1/recommendations with a manual_context (no postcode required).

• Optionally send a UK postcode; weather is on-demand and free-tier only.

• Run the same calculation through the MCP tools calculate_watering (manual, no network) and get_watering_advice (optional postcode; weather if the server has a free-tier key).

• Mount the Theme section on a Shopify page, or open the local demonstration page.

• Read the first UK knowledge pages (HTML, JSON and JSON-LD).

Requirements

• Node.js 22.23.2

• pnpm 11.5.2 through Corepack

The exact runtime is recorded in .node-version and package.json.

Quick start

corepack enable
pnpm install --frozen-lockfile
pnpm check
pnpm dev:api

The API listens on http://localhost:8787. Try:

curl -sS http://localhost:8787/v1/recommendations \
  -H 'Content-Type: application/json' \
  -d '{
    "garden_type": "borders",
    "area_m2": 12,
    "soil_class": "loamy",
    "establishment": "established",
    "irrigation_method": "watering_can",
    "manual_context": { "recent_rainfall": "light", "soil_feel": "moist" }
  }'

The response header must be X-Johgee-Data-Mode: manual. A fixture header is test-only.

Local planner page: apps/public-web/watering-plan.html (pointed at the local API).

MCP

Build the stdio server, then point Cursor or Claude Desktop at it. No API key.

pnpm --filter @johgee/contracts build
pnpm --filter @johgee/irrigation-core build
pnpm --filter @johgee/ai-tools build

{
  "mcpServers": {
    "johgee": {
      "command": "node",
      "args": ["packages/ai-tools/dist/stdio.js"]
    }
  }
}

Tools: calculate_watering (manual self-report) and get_watering_advice (UK postcode; weather on demand, otherwise the same self-report fallback). Invalid input returns a structured problem; the tools do not guess numbers. Skill draft: packages/ai-tools/SKILL.md.

A stranger should be able to run the MCP tool in about ten minutes from a clean clone: install, build the three packages above, start the stdio server.

Architecture

Shopify page / MCP client
        │
        ▼
  Public API (Hono)  ──  MCP stdio (@johgee/ai-tools)
        │                         │
        └────────────┬────────────┘
                     ▼
           irrigation-core
           (pure functions)

• Storefront: Shopify page + Theme section (extensions/watering-planner).

• Public API: https://api.johgeeirrig.co.uk/v1 (CORS: Johgee storefront).

• Core: @johgee/irrigation-core — no network, database or model.

• Anonymous share links expire in 30 days. Tokens are stored as hashes.

• Knowledge: apps/public-web/knowledge, llms.txt, sitemap, robots.

Exact UK postcodes must not enter databases, logs, traces, local storage or Git.

Repository map

apps/                     Local public-web demo
extensions/               Shopify Theme section
services/                 API
packages/                 Core, contracts, planner-ui, ai-tools, content
api/                      OpenAPI 3.1
schemas/                  JSON Schema
docs/                     Product, architecture, ADRs

Contributing

See CONTRIBUTING.md. Also SECURITY.md and GOVERNANCE.md.

Licence

Johgee-owned code is licensed under MIT. Third-party data and content keep their own terms and must be registered before use or redistribution.

Public source: github.com/hongzhizuo/johgee-open-irrigation.