B4L/Northern-Thailand-Ping-River-Monitor
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 15 Wiki Activity
Files
f4d42c90f4a3d9fd938624e6aa4936c09caaf38e
Northern-Thailand-Ping-Rive…/CLAUDE.md
T
grabowski 2e19974fad docs: README describes the project that exists; CLAUDE.md for agents 
The README was the original template: P.1 "in Nakhon Sawan", P.103 "in
Bangkok", VictoriaMetrics as the recommended database, Docker/Grafana
sections, github.com/your-username support links. Rewritten around what
runs: sources, gap fill, the forecast and its 13 h result, the live API
table, systemd deployment with the retrain timer, repository layout,
real docs links, data-source credits. Other DB adapters are mentioned as
supported-but-not-production.

CLAUDE.md replaces the untracked Ruflo boilerplate with project rules:
Python 3.11, format/test gates, Bangkok timestamps, harness-first model
changes judged on lead, the RainUnavailableError guard, no git add -A.
2026-09-11 23:44:43 +02:00

2.1 KiB
Raw Blame History

CLAUDE.md

Guidance for AI coding agents working in this repository.

What this is

Flood monitoring and forecasting for the Ping River, Chiang Mai. Public dashboard and API at https://water.buildfor.life/ (never publish the server's private/Tailscale IP). Production: one systemd unit on a small VPS, /opt/thailand-water-monitor, user water-monitor, interpreter .venv/bin/python (uv-managed), updated by git pull.

Rules

  • Python 3.11 only. uv sync --python 3.11; run everything as uv run ....
  • make format (black 88 / isort black profile, config in pyproject.toml) before committing; CI fails on formatting. make test must stay green — tests are synthetic-data only, never add one that needs the DB or network.
  • Timestamps everywhere are Asia/Bangkok wall-clock with no offset. The dashboard parses them with parseTs() and renders with timeZone: TZ; keep it that way.
  • Model changes go through the rolling-origin harness (scripts/evaluate_variants.py) and are judged on first-alert LEAD and false alarms, not MAE. Record results, positive or negative, in docs/FLOOD_FORECASTING.md section 5. Do not change what is deployed (rise_rain / hgb-v3) without a harness result that beats it on lead.
  • train_all() must never silently produce a gauge-only (v2) model; the guard that raises RainUnavailableError stays.
  • No git add -A: zero-byte shell-accident files (#, $(wc, ...) have been committed before. Stage files by name.
  • Do not add Co-Authored-By trailers.
  • The dashboard is a single file, src/static/dashboard.html, EN + TH via the t() table: every user-visible string needs both languages.

Where things are

  • src/web_api.py FastAPI app; src/water_scraper_v3.py RID collector; src/hii_collector.py ThaiWater/HII; src/ml/ features/train/evaluate/predict, rain.py (Open-Meteo), dam.py, hii_rain.py.
  • scripts/retrain.sh + water-monitor-retrain.timer: monthly retrain with staged promote. scripts/dev_proxy.py: serve the working-copy dashboard against the live API.
  • docs/FLOOD_FORECASTING.md is the authoritative model write-up; docs/DATA_SOURCES.md the source catalog.
Reference in New Issue View Git Blame Copy Permalink