# Johgee Open Irrigation

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

[Try the Johgee UK Watering Planner](https://johgeeirrig.co.uk/pages/watering-plan)
· [Read the UK watering guides](https://data.johgeeirrig.co.uk/knowledge/)

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

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

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

```sh
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.

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

```json
{
  "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`](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

```text
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

```text
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](CONTRIBUTING.md). Also [SECURITY.md](SECURITY.md) and
[GOVERNANCE.md](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](https://github.com/hongzhizuo/johgee-open-irrigation).