feat: Spotify listening analytics

[mattDev0]

Adds a listening-analytics service and a dashboard panel for it.

What Spotify can and cannot answer

Verified against the live API before building, because it shapes the whole design:

Top artists / tracks	available, three fixed windows
Recently played	last 50 plays only
audio-features	403 — deprecated for newer apps
recommendations	404 — removed
Listening time, per-hour/day history, monthly trends	not exposed at all

So half of a "Spotify Wrapped" cannot be computed from the API. apps/spotify-service therefore builds its own history: it polls recently-played every 20 minutes and stores plays in SQLite keyed on (track_id, played_at), which is what the overlapping response windows dedupe against. Genres come from the artists endpoint and are cached, being effectively static.

The UI says this plainly rather than showing an empty chart — the patterns panel carries a note that history accumulates from when tracking started.

Backend

• Timezone: bucketing honours SPOTIFY_UTC_OFFSET_HOURS. Spotify timestamps are UTC and "when do I listen" is meaningless in anything else. A fixed offset suits zones without DST.
• Stable axes: hour and weekday endpoints emit every slot including empty ones, so the chart doesn't reflow as data arrives.
• Input validation: time_range checked against an allowlist in both the service and the orchestrator proxy rather than forwarded.
• Constant-time service-key comparison.
• Scope logging on every token refresh. A silently narrowed scope is what left the portfolio's Spotify panel stuck on "Offline" for two weeks; this makes it visible.
• History lives on a named volume so it survives redeploys.

The orchestrator proxies /api/spotify/** behind an allowlist, so the dashboard keeps using the existing JWT boundary. Four new security tests cover unknown resources, invalid range, invalid kind, and unauthenticated access.

Frontend

Two panels in one row — the same footprint as the deployments row. The first draft was four rows, which put a music panel above deployments in the hierarchy of a DevOps console; tabs carry the detail instead.

Charts are single-series, so one hue and no legend: the bars encode magnitude, not identity.

Worth recording from the palette validator:

--accent-primary #6366f1 ↔ --accent-secondary #8b5cf6
  ΔE 0.8 (protan) · 6.3 (normal vision)

The two design-system accents are effectively the same colour and must never encode different things in one chart. They already appear side by side elsewhere on the dashboard as decoration, which is fine — but it rules them out as a categorical pair.

The peak bar uses the lighter step plus a hover label: same series under secondary encoding, not a second category.

Resource cost

48 MiB limit, bringing declared limits to 624 MiB on an 892 MiB host with 4 GiB of swap. Measured at ~25 MiB in use.

Deploying

Needs four values in the server .env — SPOTIFY_CLIENT_ID, SPOTIFY_CLIENT_SECRET, SPOTIFY_REFRESH_TOKEN, SPOTIFY_SERVICE_KEY, plus SPOTIFY_UTC_OFFSET_HOURS=1. .env.example documents them and scripts/authorize.py obtains a refresh token with the required scopes.

The service will not start without them, so do not merge until they are on the host, or the deploy's health check will fail.

Verified against a live account: 50 plays captured, genres, discovery ratio and hourly buckets all returning real data.