Frank
e430b6dbad
- Homepage Design Grilling.md: final decision table (Q1-Q43) + the deltas where the operator changed the recommendation (per-service probe method, 5s timeout, TUI panels, toggleable styling, no cursor alteration, no auto-refresh, /docs/ path, user-facing docs, git-driven deploy, full TDD, last-deploy footer). - Homepage.md: updated to the settled design (per-service probe, 5s, TUI panels, styling toggle, no auto-refresh, /docs/ workstream, git-driven deploy, TDD). - pi log.md: 2026-08-23 entry recording the settled design and build order. Build order is unblocked. No homepage code built yet.
5.4 KiB
5.4 KiB
Homepage Design Grilling
The decision log for the homepage design. All questions are settled (2026-08-23). This page records the final decisions and the places where the operator's answer changed the initial recommendation.
Final decisions
| # | Decision | Value |
|---|---|---|
| Q1 | How the page learns up/down | Server-side checker writes status.json; the page reads only that file. (Documented future intent: client-side probing.) |
| Q2 | How the checker runs | systemd timer, rewrites status.json every 3 minutes. |
| Q3 | Page model | Single site on Dankclaw. Root = user services (no host labels). /admin/ = admin services, second operator-only password. |
| Q5 | Service split | User: SearXNG, ComfyUI, OpenWebUI, Gitea, Calibre-Web, RomM, Copyparty, Plex, Jellyfin. Admin: Hermes, Grafana, Prometheus, Loki, Caddy, dnsmasq, Gluetun, LLM fleet, low-level backends (status-only). The *arr stack is excluded. |
| Q6 | Tourist /how/ page |
Defer — it is extra. |
| Q7 | status.json |
One file; each service carries a category field; each page filters. |
| Q8 | services.json |
One file with a category field. |
| Q9 | Checker language | python3. |
| Q10 | Probe method | Per service — tcp or http, set per entry. |
| Q11 | Probe timeout | 5 s per service. |
| Q12 | LLM loading | Three states; a listening port is Up (health 503 = Up). |
| Q13 | Checker location | scripts/homepage-status.py + .service + .timer, tracked in git. |
| Q14 | Reach backends | probe = full host:port (127.0.0.1:PORT or 192.168.0.235:PORT). |
| Q15 | WIP | static "wip": true; the checker skips the probe. |
| Q16 | Staleness | generated_at in status.json; the page warns when it is older than 10 min. |
| Q17 | Writes | atomic (write a temp file, then rename). |
| Q18 | Admin password | CADDY_ADMIN_HASH in the host .env (git-ignored), operator-only. |
| Q19 | Per-path basicauth | @admin path /admin/* with a second basicauth block. |
| Q20 | Descriptions | hand-written one-liners in services.json. |
| Q21 | Open link | the Caddy site URL; status-only backends set showLink: false. |
| Q22 | Docs link | a per-service /docs/ page. Do NOT link the existing reference docs (they may contain secrets). |
| Q23 | Layout | TUI-style cards/panels (a grid of panels), not a flat list. |
| Q24 | Summary line | yes — a placeholder for now; refine later. |
| Q25 | Terminus | bundle the font (woff2) + a monospace fallback. |
| Q26 | Palette | as proposed (green #33ff66, red #ff5555, amber #ffcc33, cyan #33ccff, bg #050805). |
| Q27 | Styling | toggleable: default = full theme; a toggle strips to bare unstyled HTML (motherfuckingwebsite.com style). |
| Q28 | Cursor | do not alter the user's cursor. |
| Q29 | Docs content | how a regular user uses the service; no maintenance details. |
| Q30 | Docs path | /docs/<svc>/ (not /usage/). |
| Q31 | Docs auth | the same auth as the homepage section (user docs = shared password, admin docs = admin password). |
| Q32 | Docs workstream | a separate effort; built as each service goes active. |
| Q33 | Deploy | git-driven; master always reflects the deployed state. |
| Q34 | /srv/homepage/ |
deploy.sh creates it and copies the assets. |
| Q35 | Timer | enabled at boot. |
| Q36 | Checker tests | full TDD. |
| Q37 | Page/config tests | full TDD. |
| Q38 | Security test | full TDD. |
| Q39 | Backend move | a config edit (probe host:port). |
| Q40 | LAN timeout | 5 s. |
| Q41 | Auto-refresh | no — the page reads status.json once on load. |
| Q42 | Mobile | responsive. |
| Q43 | Footer timestamp | last master deployment datetime (not last-check). |
Styling (settled): terminal TUI, Terminus (monospace fallback), green-on-black, 1995 phosphor palette. Default = full theme; a toggle strips to bare unstyled HTML. Do not alter the user's cursor.
Where the operator changed the recommendation
These are the deltas from the initial recommendations. Everything else was accepted as recommended.
- Q10 — the probe method is per service (
tcporhttp), not TCP-only. - Q11 / Q40 — the probe timeout is 5 s (not 3 s).
- Q22 — the docs link points to a per-service
/docs/page, never the existing reference docs (they may contain secrets). - Q23 — the layout is TUI-style cards/panels, not a flat list.
- Q27 — styling is toggleable: the full theme by default, with a toggle to bare unstyled HTML.
- Q28 — do not alter the user's cursor (no fake blinking cursor).
- Q29 — the docs are user-facing only; no maintenance details.
- Q30 — the docs path is
/docs/(not/usage/). - Q31 — the docs use the same auth as the homepage section.
- Q33 — git-driven; master always reflects the deployed state.
- Q36–Q38 — full TDD.
- Q41 — no client-side auto-refresh.
- Q43 — the footer shows the last master deployment datetime (not last-check).
Build order (unblocked)
flowchart LR
A[write the checker tests] --> B[write the checker]
B --> C[write services.json]
C --> D[write the pages + theme + toggle]
D --> E[extend deploy.sh + Caddyfile]
E --> F[tests green]
F --> G[deploy to Dankclaw]
G --> H[verify in browser]
The per-service docs pages (Q22/Q29/Q30/Q31) are a separate workstream, built as each service goes active.