# CLAUDE.md

This file provides guidance to Claude Code when working with this repository.

## Project Overview

`river_monitor.py` polls the UK Environment Agency's real-time flood-monitoring API for river level stations within a configurable radius, archives readings to a local SQLite database, and optionally generates a self-contained HTML dashboard.

## Synology / Website Integration

The primary deployment target is a Synology NAS running Web Station, alongside the `simon/web` Gitea repo (theatari.com). The poller runs via DSM Task Scheduler (`synology-task.sh`) every 15 minutes with `--no-html`, writing only to the SQLite database. A `river.php` page in the web repo reads the DB and renders the dashboard as part of the site.

### Database

The DB is written to `data/river_levels.db` inside the web repo on the Synology (path configured in `synology-task.sh`). That directory is already shielded from direct web access by `data/.htaccess`.

**Schema:**

```
stations: station_id TEXT PK, label TEXT, river_name TEXT, lat REAL, lon REAL

readings: id INTEGER PK, station_id TEXT, measure_id TEXT, unit TEXT,
          qualifier TEXT, value REAL, date_time TEXT, fetched_at TEXT
          UNIQUE(measure_id, date_time)
```

**Useful query — latest reading per station:**

```sql
SELECT s.label, s.river_name, r.value, r.unit, r.date_time
FROM stations s
JOIN readings r ON r.station_id = s.station_id
WHERE r.date_time = (
    SELECT MAX(date_time) FROM readings WHERE station_id = s.station_id
)
ORDER BY s.label;
```

**Useful query — recent history for sparklines (last 50 readings per station):**

```sql
SELECT station_id, value, date_time
FROM readings
WHERE station_id = ?
ORDER BY date_time DESC
LIMIT 50;
```

### Instructions for the web repo Claude

When adding the river page to `simon/web`:

- Create `river.php` following the same structure as `blog.php`: open the DB with `new SQLite3('data/river_levels.db', SQLITE3_OPEN_READONLY)`, include `includes/header.php` and `includes/footer.php`, and render using existing CSS classes and custom property variables (never hardcode colours).
- Add a "River" nav link in **all 6 nav locations**: `index.html`, `links.html`, `gifs.html`, `games.html`, `contact.html`, and `includes/header.php`. Mark it active in `river.php` the same way blog pages mark the Blog link active via `blog_nav_active()`.
- The page should show current level + a small trend sparkline per station, consistent with the existing card/grid style.
- Chart.js (already used in the standalone dashboard) can be loaded from CDN the same way other external scripts are used on the site.