arr-summary/CLAUDE.md

Arr Summary (Greendale)

Flask dashboard aggregating status from the user's self-hosted media stack — Sonarr, Radarr, SABnzbd, Tautulli, Prowlarr, Ombi — plus Unraid array stats and a Rotten Tomatoes "what's popular that I don't have yet" feed. Branded "Media Centre". Since v2.0.0 (2026-08-29) it presents as a broadcast information service in the teletext tradition: numbered pages you reach by typing the number, status carried by colour, and no borders or cards anywhere. This replaced — not refined — the earlier neutral dark card theme, which had itself replaced five novelty themes. See DESIGN.md for the visual system and the static/css/base.css header for the five disciplines it is held to. Runs as one Docker container on the user's Unraid home server. Server-side project directory is still named greendale; the container/repo are named arr-summary.

Architecture

• app.py — single Flask app, session-based single-shared-password auth (LOGIN_PASSWORD env var, hashed comparison; can be changed at runtime via /api/change-password, persisted to settings.json). Supports running behind a reverse-proxy subpath via SCRIPT_NAME + ScriptNameMiddleware + ProxyFix (currently deployed at domain root, not a subpath, but the capability exists — see nginx/ configs for both).
  • Per-service client functions (sonarr_get, radarr_get, sabnzbd_get, tautulli_get, prowlarr_get, ombi_get) each call that service's REST API directly with its API key from env vars.
  • The dashboard route (/) fetches all services in parallel via ThreadPoolExecutor with a hard 5-second wall-clock deadline — any slow/unreachable service degrades to an error dict rather than blocking the whole page. This matters for remote/cellular access.
  • Aggressive per-service caching with different TTLs tuned to how often each actually changes: Sonarr/Radarr library lists 5 min (the biggest latency cost — full Radarr list is ~4.4MB), Tautulli stats 2 min, SABnzbd history 10 min, Ombi requests 4 hours, Rotten Tomatoes scrapes 4 hours. Active streams (Tautulli) and the SABnzbd queue are always fetched live, never cached — those need to be current-second accurate.
  • Rotten Tomatoes / IMDB are scraped directly (requests + BeautifulSoup, JSON-LD parsing), not via an official API — brittle to upstream HTML changes by nature.
• templates/ — Jinja2 templates. _shell.html is the root layout every page extends; _macros.html holds the shared fragments. Pages are home.html (P100), watch.html (101), library.html (102), discover.html (103), requests.html (104), system.html (105), activity.html (106), settings.html (900), plus login.html, which stands alone. The old single-page dashboard.html was deleted in the v2.0.0 redesign along with dashboard.css, login.css, settings.css and dashboard.js.
  • Templates carry markup only. CSS and JS live in static/ and are linked via url_for('static', ...) so they stay correct behind a SCRIPT_NAME subpath. Server-rendered config (timezone, script root, the page-number map) reaches JS through <body data-*>, never string-interpolated into a script block.
  • No style="..." attributes for anything static. A one-off tweak belongs in static/css/teletext.css, scoped with a structural selector or a small modifier class. The only legitimate inline style= is a per-request computed value Jinja has to interpolate — currently just the bar() macro's fill width.
  • _shell.html's first <body> child is an HTML comment holding the direction contract for the visual world (thesis, own-world, story, first viewport, form, seed key). Leave it in place; it is what a later session audits the design against.
• static/css/base.css — tokens and reset. Its header comment states the five disciplines the visual world is held to; read them before changing anything visual, and treat breaking one as a regression rather than a variation:
  1. No in-between tone. There are eight colours (the teletext primaries). A mid-grey is an ordered dither of two of them, never a ninth colour.
  2. No enclosure. Nothing is surrounded by a border or a box. There is zero border-radius in the codebase. Grouping is a coloured field row (.tt-field), indentation, and weight. This is the single thing the world most refuses — the previous design was built on bordered cards.
  3. One ruler. Every bar and percentage shares one scale (--bar-cells) and is drawn only by the bar() macro in _macros.html, so 60% on the array and 60% on an indexer are the same width and compare directly. Never restyle a bar per section.
  4. Every reading carries its direction. A value shows where it is heading. Only drawn where the backend genuinely holds a comparison — today that is SABnzbd speed against its stored 7-day average, and nowhere else. Do not invent a trend for data with no history.
  5. Pages differ in stock. A page holding critical state is set heavier than a quiet one (.tt-field.warn / .tt-field.crit). Uniform texture across all the pages is a failure.
  • Colour is semantic, never decorative: yellow is the service's own voice, cyan is a live value, green is healthy, red is off air, magenta means a human must decide (pending requests only), blue is a field ground. Reshading means editing the eight tokens here, nothing downstream.
  • Type is one face at exactly two heights — --fs (15px) and --fs2 (30px, double height). Adding a third size breaks the system. The 16px literal on inputs is deliberate: it prevents iOS zoom-on-focus.
  • --ink-dim (58% white) is the only dimmed token allowed to carry text; it clears 4.5:1 on black. --ink-dimmer (30%) is for graphics only — bar troughs, the dither field, separators. Setting text in --ink-dimmer fails contrast, which is exactly the bug the redesign's first inspection round caught.
  • Navigation is the page number. Typing any three digits anywhere jumps to that page, and r/g/y/c fire the four fastext colour keys — both in static/js/service.js. nav_items in app.py is the source of truth for the numbers and is serialised into <body data-pages>.
  • Nothing is clipped, hidden, or sticky. All seven page numbers and all four fastext keys stay visible at every width, reflowing to another row rather than scrolling, truncating, or folding into a menu. No header is sticky.
• export-to-unraid.sh — a pre-existing standalone deploy script (build image locally → tarball → rsync + docker load over SSH) that predates the Forgejo pipeline below. Still present, not removed, but the Forgejo pipeline is now the primary deploy path going forward.
• nginx/ — reference nginx location-block snippets for subdomain vs. subpath reverse-proxy setups; not actually consumed by the app at runtime (NPM handles proxying in practice), kept as documentation/config reference.

Local development

pip install -r requirements.txt
python3 app.py

Runs on port 5000. Needs the various *_API_KEY and *_HOST/ARR_HOST env vars (see .env.example) to reach real services — without them, dashboard cards degrade to "error" status individually rather than crashing the page.

Expect every service to be offline on the dev machine, and expect /api/* polls to 500. The dev laptop is not on the network with the media stack, so Sonarr/Radarr/SABnzbd/Tautulli/Prowlarr/Ombi all refuse the connection: every card renders its service_error() state, the header pills all read "offline", and the browser console fills with 500 responses from the live-poll endpoints (/api/sabnzbd and /api/tautulli poll on a timer, so they repeat every few seconds). This is the normal local baseline, not a regression — don't go debugging it, and don't "fix" it. If you need to check whether a 500 is genuinely yours, stash the working tree and confirm the same response on a clean checkout.

Because of that, the only reliable way to exercise a card's real (non-error) rendering locally is to monkey-patch its fetcher and run the app on a spare port, e.g.:

LOGIN_PASSWORD=test python3 -c "
import app as a
a.get_unraid_stats = lambda: {'status': 'ok', 'source': 'api', ...}
a.app.run(host='127.0.0.1', port=5099)"

Two gotchas when doing this: Jinja's auto_reload follows app.debug, which is off, so template edits need a server restart — a browser reload alone will silently serve the cached template. And the login password comes from LOGIN_PASSWORD, so set it explicitly rather than hunting for the real one.

The listen port comes from PORT (default 5000, matching EXPOSE, gunicorn.conf.py and the ${HOST_PORT}:5000 compose mapping — change all four together or none). Set it when running locally: macOS ControlCenter already holds port 5000, so python3 app.py with no PORT will fail to bind on the dev laptop. .claude/launch.json sets autoPort so a dev harness can assign a free one, but note that on this machine the preview sandbox can't read files under ~/Desktop ("Operation not permitted"), so launching by name fails and running the app from a shell on an explicit PORT is the working path.

Deployment

Target: Unraid server, container path /mnt/user/appdata/greendale (note the directory name differs from the container/repo name), built from Dockerfile/docker-compose.yml in this repo. Container name arr-summary, port 5055 (overridable via HOST_PORT) → container port 5000.

Deploy mechanism: Forgejo push-to-deploy, same pattern as the other three projects on this box — see card-grader's CLAUDE.md for the full pipeline mechanics. Push to main on the forgejo remote (https://git.hippofam.com/ninja_hippo/arr-summary.git) triggers .forgejo/workflows/deploy.yml, which syncs into /mnt/user/appdata/greendale (excluding .git, .env, data/) and runs docker compose up -d --build.

Restarting the container manually: use Compose, not the Unraid Docker UI. Every deploy recreates the container with a new Docker ID (same name, arr-summary). Unraid's Docker tab caches the old ID, so hitting Restart there after a deploy throws "No such container" — harmless, but confusing. From the Unraid terminal:

cd /mnt/user/appdata/greendale && docker compose restart

docker compose up -d --force-recreate for a guaranteed-clean recreate; docker ps --filter name=arr-summary to check real state regardless of what the Unraid UI shows.

Confirming a deploy actually landed: the dashboard footer renders v<APP_VERSION> · <APP_VERSION_DATE> from constants near the top of app.py (both env-overridable, injected into every template by the inject_version context processor). Bump them when cutting a deploy — loading the page is then the quickest honest check that the new build is live, without trusting the Unraid Docker tab's cached container IDs.

Reverse proxy (Nginx Proxy Manager)

Two NPM proxy hosts front this app and git.hippofam.com, both using Let's Encrypt certs issued via DNS-01 through Porkbun — required, not optional: Cox blocks inbound port 80 on this connection, so HTTP-01 challenges (and plain http:// requests generally) can never work here. http://hippofam.com will always time out from outside the LAN; only https:// resolves. Both proxy hosts have Force SSL on.

hippofam.com → http://192.168.86.33:5055 (the Unraid box, this container's port). Verify the destination IP/port here before assuming an outage is DNS or app-level — it has drifted to the wrong host before.

On 2026-08-26 the apex host's own cert (issued Aug 2025) went dark: NPM's UI still showed it "In Use" with a valid, unexpired date, but nginx presented no certificate at all for hippofam.com (TLS alert 112, "unrecognized name") — the on-disk cert files had rotted independently of the DB record NPM's UI reads from. git.hippofam.com, on a newer cert from the same account, was unaffected. Fixed by pointing the proxy host at the *.hippofam.com + hippofam.com wildcard cert already issued and sitting unused, which forced NPM to regenerate the nginx config with known-good cert files. If hippofam.com ever throws a TLS handshake error again with NPM's UI reporting all green, suspect this same on-disk/DB drift before anything else — check with:

openssl s_client -connect <public-ip>:443 -servername hippofam.com </dev/null

A clean run shows subject=/CN=... and Verify return code: 0; the broken state shows no peer certificate available.

Persistent state, never touched by deploys: .env holds every API key and LOGIN_PASSWORD — this project was already doing this correctly before the Forgejo migration (compose file uses ${VAR} substitution from .env, no hardcoded secrets), unlike n64-tracker which needed fixing. Runtime settings written by the Settings page (API-key overrides, timezone, changed login password) live in settings.json at SETTINGS_FILE, which the compose file points at /data/settings.json on the ./data bind mount — i.e. /mnt/user/appdata/greendale/data. That mount is load-bearing: without it the file sits on the container filesystem, and every up -d --build recreates the container and silently discards it. data/ is likewise excluded from the deploy rsync, which runs --delete and would otherwise remove it for not being in the repo.

Logins

Two modes, chosen by whether settings.json holds a non-empty users map:

• Multi-user (once any account exists): username + password, each password stored as a salted pbkdf2 hash under users in settings.json. verify_credentials() is the only entry point; load_users() re-reads the file per check, so adding a user or changing a password is live immediately in every gunicorn worker — no restart, unlike the API keys.
• Legacy single shared password (no accounts yet): the original LOGIN_PASSWORD / settings.json.login_password path, username ignored. This fallback exists so deploying multi-user support can't lock an existing install out; the login page hides the username field entirely until accounts exist.

Manage accounts with manage_users.py, which prompts for passwords (never echoed, never a CLI argument, so they stay out of shell history) and only ever writes hashes:

docker exec -it arr-summary python3 manage_users.py list
docker exec -it arr-summary python3 manage_users.py add <username>
docker exec -it arr-summary python3 manage_users.py passwd <username>
docker exec -it arr-summary python3 manage_users.py remove <username>

Adding the first account switches the whole dashboard to per-user logins and the shared password stops working — verify you can sign in as that user before closing the shell. remove refuses to delete the last account for the same reason.

Users live in settings.json rather than an env var deliberately: a pbkdf2 hash contains $, which docker compose interpolates when reading .env. PASSWORD_HASH_METHOD is pinned to pbkdf2 rather than Werkzeug's default scrypt, which needs a hashlib built against OpenSSL and is absent on the macOS system Python.

Never put a real password in the repo — not in app.py, not in settings.json committed to git, not in a fixture. .env and data/ are gitignored and excluded from the deploy rsync precisely so secrets have somewhere to live; everything else here is pushed to Forgejo.

A key saved through the Settings page overrides the corresponding .env value at startup (see the block after the *_API_KEY reads in app.py); .env remains the source of truth for anything never overridden there. Both paths need a container restart to take effect, since the keys are read once at import.