Add structured headers to the PHP pages layer

Documents each tab's purpose, what it renders, and which endpoints it polls. Pages that start with markup get the header in a <?php ?> block so it never reaches the browser. Also corrects the layer diagram in README-unraid.md: eight of eleven pages hold no PHP logic and poll api/ for everything — only auth, monitor and scheduler require an include/ file directly.
2026-08-02 00:51:41 -04:00
parent 0b4ff27be4
commit ccc6c742ee
12 changed files with 414 additions and 5 deletions
@@ -1,3 +1,31 @@
+<?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Watchdog tab. Shows what every watchdog has recorded across all nodes — strike counts,
+//   action levels, paused and stopped containers, restart history, OOM and reboot counts.
+//
+// DESIGN PRINCIPLES
+//   Pure view. No PHP logic and no include/ dependency — the whole page is markup plus a
+//   poll against api/watchdog.php. All parsing lives in include/watchdog.php behind that
+//   endpoint, so the page cannot hold a second opinion about what a strike means.
+//
+//   Shows every node, not just this one. A watchdog page that only covered the host you
+//   happened to open it on would miss exactly the node in trouble.
+//
+// OPERATIONAL SAFEGUARDS
+//   Strictly read-only. There is no control on this page that clears a strike, restarts a
+//   container, or resets a counter — those belong to the watchdog that owns the state.
+//
+//   A node that fails to report renders as unavailable rather than healthy. Absence of data
+//   is never drawn as an all-clear.
+//
+// RENDERS
+//   Per-node cards: resource / docker / system / storage / network watchdog state,
+//   strike pills, restart history, reboot and OOM counts
+//
+// DEPENDS ON
+//   api/watchdog.php   polled every 30s   → include/watchdog.php
+?>
 <style>
 .vv-wd-card    { background:#161616;border:1px solid #2a2a2a;border-radius:6px;padding:10px;min-width:0; }
 .vv-wd-sec     { font-size:10px;font-weight:bold;color:#444;letter-spacing:.07em;text-transform:uppercase;margin-bottom:6px; }