dashboards/.agents/PLAN.md

Homelab Dashboards — Master Plan

Master design document for a phased-execution project. The phase roadmap below was derived from TODO.md on 2026-10-16; each phase overview and task file cites its source lines in that file. The LOCKED DECISIONS below are binding: no phase may introduce technology outside them without explicit user permission.

AGENTS.md (repo root) is the sibling document: the invariants, the fleet facts, and the known gaps. It is not superseded by this file — read both.

Assumptions & Design Principles

• The dashboard's job is a fast, honest glance. Every TODO item is a legibility complaint, not a feature request: the same truth with less ink and clearer colour.
• One colour language. Green/amber/red means exactly one thing across all four pages, computed server-side in Python so it is unit-tested and cannot drift per page.
• Fewer numbers, larger. Removing a metric from a page is a feature, but only when the history stays in the DB. Pages stop plotting what the operator stopped asking for; the stored series are kept so the decision is reversible.
• The existing pages are payload-driven and stay that way. No page scrapes HTML, no page grows its own business logic. If a card needs a judgement ("is 5.3 years old bad?"), the API supplies it.
• Charts stay hand-rolled SVG. llm_monitor's per-cell sparklines are the reference for "useful and readable"; they are inline SVG with no library, which is exactly the house style, so they port rather than get replaced.
• Every UI change is verified in a browser against live data (AGENTS.md definition of done) — a screenshot in data/logs/, not a claim.

Architectural Anchors

COMPONENT	DECISION	RATIONALE	STATUS
Backend	FastAPI, single process, one domain, four routes (/, /system, /llm, /ups)	Inherited from the existing code	LOCKED
Frontend	Vanilla JS + one stylesheet. No framework, no CDN, no build step, nothing fetched at runtime	The engines live on a network with no outbound access; a CDN reference is a dead request	LOCKED
Charts	Hand-rolled SVG in web/static/charts.js	Same reason as above; llm_monitor proved it works for a year	LOCKED
History	SQLite (sample(source,host,metric,res,ts) + event), raw → 1m → 1h rollups	Inherited; bounded, no TSDB to operate	LOCKED
Writes	Read-only except POST /api/ups/command, gated four times	Invariant 1 of AGENTS.md	LOCKED
API shape	Additive only: existing /api/* fields keep their names and meaning	The four pages, the live tests, and future consumers depend on them	LOCKED (ratified 2026-10-16)
Severity	New src/dashboards/severity.py is the only place thresholds live; API responses carry severity per value; CSS/JS only render the class	Testable once, identical on every page; JS business logic is untested by definition	LOCKED (ratified 2026-10-16)
JS tests	None added. Coverage gate (>90%) applies to new/modified Python; UI is proven by payload-contract tests plus browser screenshots	Adding a JS toolchain would violate the no-build-step anchor for no extra confidence in the colour logic	LOCKED (ratified 2026-10-16)
Dropped visuals	Per-core CPU charts and shared multi-host charts are removed from /system; the underlying series stay in SQLite	Explicit user request; reversible because nothing is deleted from history	LOCKED (ratified 2026-10-16)
Toolchain	Python 3.14, pytest, ruff, pyright, uv	Inherited; the lock resolves for 3.14 only	LOCKED
Planning tree	.agents/ is tracked and committed; .agents/phase-sessions/ and .agents/pipeline.log are ignored	The roadmap is project history, not scratch	LOCKED (ratified 2026-10-16)

High-Level Architecture

agent/host_agent.py (each host)      gufo / vLLM            upsd (NUT, port 3051)
        │ GET /snapshot                    │ GET /metrics           │ LIST UPS / LIST VAR / LIST CMD
        ▼                                  ▼                        ▼
collectors.py ─── fetch, one UpstreamError type ────────────────────────────────┐
        │  parse                                                                 │
        ▼                                                                         ▼
sources/host.py · sources/llm.py · sources/nut.py                 poller.py (task per source)
        │   Result(payload, samples, events)     ◄── NEW: severity.py classifies values
        ▼                                                                         ▼
store.py ── SQLite (WAL): sample + event ──────────────────────────► api.py ──► web/
                                                                     /api/summary is the
                                                                     overview's one call

Pages and their scripts (src/dashboards/web/):

Page	HTML	Script	Charts it builds today
/	pages/index.html	page-index.js	none (three summary cards + fleet table + events)
/system	pages/system.html	page-system.js	#chart-cpu, #chart-mem, #chart-disk, #chart-net, #chart-gpu, #chart-temp, #chart-detail — all shared, multi-host
/llm	pages/llm.html	page-llm.js	#chart-decode, #chart-prompt, #chart-kv, #chart-queue
/ups	pages/ups.html	page-ups.js	battery charge, runtime estimate, voltages, load

Shared helpers: app.js (nav, poll loop, fetchJSON, formatting), charts.js (DashCharts.LineChart, escape/axis helpers), dash.css (tokens, cards, bars).

Data Model

• sample(source, host, metric, res, ts) — source ∈ {host, llm, ups}; res ∈ {raw, 1m, 1h}; metric is dotted with @stream for per-device series (cpu.usage_pct@core7, disk.used_pct@/srv, gpu.busy_pct@0). The metric namespace is a public interface: phases may stop plotting a series, they may not rename or stop storing it.
• event(ts, source, kind, severity, message) — transitions only, which is what the overview's alert list will reuse.
• Host payload (/api/system/snapshot, per host): cpu.{usage_pct,temp_c,load1}, memory.used_pct, disks.{worst_used_pct,worst_mount,util_pct}, network.{rx_bytes_per_s,tx_bytes_per_s,interfaces[]}, gpus[].{busy_pct,vram_used_bytes,vram_total_bytes,vram_used_pct,mem_used_pct,temp_c}, temperatures.{cpu_c,max_c}, processes, agent.errors. Everything the per-host cards ask for already exists — phase 03 tests the contract rather than inventing fields.
• UPS payload (/api/ups/snapshot): per card status, states[], on_battery, numbers (charge_pct, load_pct, battery_runtime, battery_voltage, line_voltage, battery_temperature), health.{overall,severity,checks[],counts}, commands[] (each with enabled, reason, confirm_text, risk), simulated at the top level. Real fleet today: apc (APC Back-UPS RS 1500MS) and cyberpower (CyberPower PR1500LCDRT2U) on driveripper's upsd at port 3051, forwarded to 127.0.0.1:3494 in dev. Neither driver reports a battery temperature; battery.mfr.date is the only date that means anything.
• /api/summary returns {ts, system:{enabled,fleet,hosts[],states}, llm:{...}, ups:{...}, recent_events[]} — phase 02 adds alerts and the overview page shrinks to fleet+alerts.

Validation / Verification Workflow

Per task, in order:

1. uv run pytest — hermetic, no network; must stay green (baseline at conversion: 258 passed, 6 skipped, 94% coverage).
2. uv run pytest --cov — coverage on new/modified Python >90%; overall must not drop below 94%.
3. uv run ruff check src tests agent && uv run pyright — clean.
4. uv pip list --outdated — empty whenever dependencies moved.
5. uv run pytest -m live --live (with .env.dev sourced) — the opt-in suite that drives the production code paths against the real fleet, both engines, and real upsd. Baseline: 6 passed. UI phases must not break it.
6. Browser verification of every touched page with live data, screenshot saved to data/logs/ (./scripts/dev-server.sh restart keeps http://127.0.0.1:8090 up).
7. Commit per task with --no-gpg-sign and the LLM-Generated: true trailer.

Phase Roadmap

#	Phase	TODO source	Objective (one line)
01	01_severity_language	TODO.md L5, L7 (colour-coding clauses)	One server-side threshold table + severity on every value the pages colour, plus the CSS/JS vocabulary to render it
02	02_overview_fleet_and_alerts	TODO.md L3	Overview is fleet + warnings/errors and nothing else
03	03_system_per_host_panels	TODO.md L4, L5	/system is per-host hero cards (cpu/mem/temp/disk/gpu/net, no per-core) with per-host charts, no shared charts
04	04_llm_chart_readability	TODO.md L6	LLM page readable again: per-cell sparklines and percentiles in the llm_monitor idiom, big colour-coded rates
05	05_ups_hero_battery_glyph	TODO.md L7	Charge / load / runtime big and colour-coded, with an SVG battery that shows charge

There is deliberately no foundation phase: pytest, ruff and pyright are configured, the suite is green, and the project launches, which are the only conditions that would have required one.