Northern-Thailand-Ping-River-Monitor/docs/DASHBOARD_REDESIGN.md

Dashboard redesign: the console

Status: phase 3 done (2026-10-19). The new dashboard is built next to the current one and replaces it in phase 4.

• Preview: https://water.buildfor.life/static/console.html, after git pull on the server (static files are read per request, no restart). It is not indexed (noindex) and links back to the current dashboard.
• Locally: uv run python scripts/dev_proxy.py 8765, then http://localhost:8765/static/console.html. The API is proxied to production.
• Rules: the same as for dashboard.html, plus no emoji (tests/test_console.py):
  • every path it fetches is a Rust route;
  • every string exists in EN and TH, and Thai is the default;
  • timestamps are Bangkok wall-clock time.

Why: the current page

Observed on 2026-10-19 at 1440 px and on a 390 px phone.

• No clear first answer. "Is Chiang Mai flooding?" is a thin green banner above four KPI cards of equal weight. Two of them answer nothing for a resident: "Most stressed gauge 16%" and "Chiang Mai river flow 53.9" (no unit in the number). At the bottom there are five more (2,700,706 datapoints, 3,002 days, …).
• The colours answer the wrong question. Markers and river lines are coloured by discharge class (m³/s), not by distance to the warning level, and the station list shows discharge.
• The map is noisy. OSM terrain with Thai labels, numbered markers and animated dashes. The legend covers about a third of the map, and more than half of the first phone screen.
• The header is busy. It has six buttons with emoji (↻ 🌙 🔔 ▶); on a phone they wrap into three rows.
• Internal detail on the main page. The model-skill table lists seven model hashes; the history card is an empty 360 px box until a station is clicked.
• Inconsistent styling. A gradient background, several card and pill styles, three greens.

Decision

Two directions were sketched on 2026-10-19 against live data (throwaway HTML, not kept):

• A: a public information page.
• B: an operations console.

The user chose B.

Layout

One screen, no page scroll on a desktop:

Area	Content
Top bar	brand · Chiang Mai verdict (P.1 level + 24 h forecast, always visible, click selects P.1) · gauges reporting · highest 24 h flood chance · data age · EN/ไทย · light/dark · Get alerts
Left	two lists: RID gauges (status bar, code, name, margin to the warning level, 72 h sparkline, level and 6 h change; sort by river order, closest to the warning level, rising) and Basin stations (ThaiWater/HII: % of bank height, river and agency; sort fullest first or by name); filter; legend
Centre	map on a self-hosted vector basemap (labels in the page language): Ping mainstem and tributaries, gauges coloured by status with code + level labels, layers Basin stations (diamonds), Rain 24 h and Flood zones, the team's markers from zoom 12, one legend
Right	selected RID gauge: level, 6 h change, discharge, warning/danger level with margins, capacity; level scale with now and 24 h peak; history (3 d / 7 d / 30 d / 90 d / 1 y / all or dates: level, discharge, the 24 h peaks as issued, warning/danger bands, hover values; up to 7 d it ends in the current forecast); forecast table (peak, chance of warning/danger at 6/12/24 h, model, issue time, disclaimer); for P.1 the seven inundation stages, the zones toggle and "How accurate is the forecast?"; data links. A basin station shows level (m MSL), % of bank height with ThaiWater's class, distance to and height of the bank top, gauge reading, agency (latest reading only: no history is kept for them)
Status bar	data credits, "2.7M readings since 2018" (opens the data statistics), API, source code

Narrower screens:

Width	Layout
< 1280 px	The panel moves below list and map, in columns
< 860 px	One column: verdict, map, list, panel

Behaviour:

• Selection is in the URL (#P.84, #hii-1198299); opening a basin station switches to its list.
• Arrow keys move through the list.
• Data refreshes every 5 minutes.

Where every current element goes

Current (dashboard.html id)	Console	Phase
flood-verdict, verdict-*	Verdict in the top bar	1
station-count, last-updated, data-age, live-pill	Top-bar KPIs (reporting, data age)	1
river-flow, peak-station (P.1 flow, most stressed gauge)	Discharge and capacity in the panel; "Closest to warning level" sort	1
station-map, map-legend, legend-toggle, rain-toggle, zones-toggle	Map, layer buttons, one legend	1
side list, station-search	Gauge list with filter and sorts	1
forecast-card, p1-outlook, p1-peak, p1-stages, forecast-grid	Panel: forecast table for every gauge, stages for P.1	1
alerts-panel, alerts-*	Alerts drawer	1
refresh-button	Removed: refresh every 5 min, age in the top bar	1
lang-toggle, theme-toggle	EN / ไทย segmented control, icon button	1
error, loading	Map overlay with retry; "Loading" in the list	1
thaiwater-sensors, sensors-*	Basin stations list + map layer	2
custom markers	Pins from zoom 12, popup with their flood zone	2
history-card, history-*	Panel history with ranges	3
skill-panel, skill-*	Panel section for P.1	3
db-stats, db-*	Status-bar popover	3
replay-2024, replay-*, demo hooks	Replay/simulation mode with banner and mode pill	4

Design rules

• Type: Inter (Latin) and Noto Sans Thai, self-hosted in src/static/fonts/ (75 KB, OFL). Numbers use tabular figures.

• Colours: CSS variables for light and dark, with dark the default; a saved choice wins (ping-river-theme, shared with the current dashboard).

  • Accent: #1d6fd6 light, #4c9bf0 dark.
  • Status: colours are used only for status, each with an -ink variant for text (WCAG AA on white).

• One status rule (statusOf) for the map, list and panel. It is display-only; the notifier keeps its own transitions.

  Status	Rule
  Normal	none of the rules below
  Watch	within 0.5 m of the warning level, or 24 h warning chance ≥ 25 %
  Warning	level ≥ threshold_warning
  Danger	level ≥ threshold_danger
  No data	no reading for 24 h

• City verdict: the current dashboard's rule — flooding from P.1 ≥ 3.70 m; "likely" at danger ≥ 50 % or warning ≥ 70 %; watch at warning ≥ 20 % or level ≥ 3.20 m.

• Data age: "feed stale" after 3 h, except during RID's overnight pause (21:00 to 09:00 with an evening reading). The pause shows as "overnight pause", the same rule as the notifier's FEED_NIGHT_UNTIL_HOUR.

• Discharge: comes with RID's report. When the newest hour is a level-only reading, the panel shows the last RID discharge with its time ("at 14:00").

• Rain layer: off by default unless any station has heavy rain (> 35 mm / 24 h); an explicit choice is remembered.

• Flood zones: shown automatically while P.1 is at or above a stage, unless hidden by the user.

• Basin stations: ThaiWater's classes for the level as a share of the bank height (critically low ≤ 10 %, low ≤ 30 %, normal ≤ 70 %, high ≤ 100 %, over the bank). On the map and in the list over the bank is danger, high is watch, the rest normal; no data after 24 h. Gauges RID already lists are shown once, as RID gauges. The layer is off until the list is opened or the button pressed.

• History: above 2,500 readings (30 d and longer for most gauges) the chart shows the daily mean with the daily low–high band, so a flood peak is not averaged away; gaps longer than 3.5 h (2.5 days when daily) break the line rather than bridging RID's nightly pause. Short ranges reload with every refresh, long ones at most hourly. "All" asks for limit=100000: /measurements/history returns the oldest rows first and stops at its 50,000 default, which made the current dashboard's "All time" for P.1 end in October 2024 (fixed there too).

• Forecast accuracy: loaded when the section is opened (a cold /api/forecast/skill query takes up to 20 s), cached for 15 minutes; bias and persistence error are in each row's tooltip.

• Basemap: src/static/basemap/ping-basin.pmtiles, a Protomaps extract (bbox 97.85–99.95 E, 16.85–20.2 N, zoom 0–12, 15 MB, OpenStreetMap data), drawn by protomaps-leaflet 5.1.0 in its light/dark style with name:th/name:en labels. Refresh instructions in src/static/basemap/README.md. The map cannot be panned far outside the basin. OSM raster tiles are the fallback if the renderer does not load.

Phases

Each phase is one commit, checked with screenshots: 1440, 1100 and 390 px; light and dark; EN and TH.

1. Done — Console shell with live data.
   • Layout, design tokens, fonts, EN/TH.
   • Verdict and KPIs, gauge list with sparklines and sorts.
   • Map with status markers, rain and flood-zone layers.
   • Station panel (readings, scale, 72 h chart, forecast table, P.1 stages).
   • Alerts drawer (ntfy topics); URL selection; 5-minute refresh.
   • tests/test_console.py; dev_proxy.py serves src/static with proper content types.
2. Done — Map and basin.
   • Basemap: the self-hosted Protomaps extract replaces the dimmed OSM raster tiles, whose baked-in labels were the noisiest part of the screen. Labels follow the page language; light and dark styles.
   • Server: ServeDir answers HTTP range requests (checked: 206); dev_proxy.py now does too.
   • ThaiWater/HII stations: the Basin stations list and map layer, from /api/hii/waterlevel/latest, falling back to /sensors/thaiwater.
   • Custom markers: custom-markers.json as pins, with their flood-zone popup.
3. Done — Station depth.
   • History in the panel (inline SVG, no chart library): ranges and dates, level and discharge, issued 24 h forecasts overlaid, warning/danger bands, hover/touch values.
   • P.1 forecast accuracy as a collapsible panel section, from /api/forecast/skill.
   • Data statistics: a status-bar popover, from /api/stats.
4. Modes and the swap.
   • October 2024 replay: banner, clock, markers and verdict follow the replay; zones auto-show.
   • Demo hooks: ?demo_level=, ?demo_rise=. A mode pill (LIVE / REPLAY / SIMULATION) never relabels a replay or simulation as live.
   • The swap: console.html becomes dashboard.html; the old file and its tests go. tests/test_console.py absorbs the remaining checks of tests/test_dashboard.py (one P.1 level, SEO tags; the robots noindex is removed).
   • Docs: README screenshot and the CLAUDE.md rule.
5. Polish.
   • Phone layout pass.
   • Native-speaker review of the Thai strings.
   • Keyboard and screen reader pass.
   • Lighthouse ≥ 90 (performance, accessibility).
   • No console errors.

Data notes from building phase 1

• Negative levels. P.4A (−1.28 m) and P.67 (−0.59 m) report negative levels: gauge datums, not errors. The panel's scale starts at the lowest of 0 and the station's 72 h readings.
• P.1 discharge disagrees between endpoints. At 15:00 on 2026-10-19, /measurements/latest had level 1.30 m with no discharge, while /measurements/history had 26.0 m³/s with no capacity. RID's 14:00 report said 53.9 m³/s. The console shows the last RID discharge. Worth checking where the 26.0 comes from.
• P.84 spike. A one-hour spike at 13:00 the same day: 0.73 → 1.05 → 0.78 m.