river-monitor/CLAUDE.md

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:

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):

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.