Web UI and onboarding
Formerly design.md §12 and §13. The web UI is the human control surface for the whole loop: search,
suggest, approve, and watch channels and acquisitions live. The client platform, its packages and
the Tamagui migration (#970) belong to frontend-design.md; the design
mocks are the authority on layout.
Delivery
- Built assets are embedded in the Go binary and served same-origin at
/, so there is no CORS and one container. Compressible assets are gzip-encoded once per process; hashed assets are immutable for a year, and the SPA document isno-store. - Types and hooks are generated by
orvalfrom the committedapi/openapi.yaml; a contract change is a compile error.@loomarr/apire-exports DTOs type-only and only the enum objects the UI uses at run time. - Live updates come from SSE
/v1/events, which only invalidates queries; the API stays authoritative. A screen never polls for state the server changes: each such change has a frame, published after the change is stored, and the screen reads again on it (#3352). Frames sent while the stream is down are gone, so when it opens again every read a frame feeds refetches. A client too slow to take a frame is disconnected rather than left with a gap, so it reconnects and refetches the same way. The browser retries a dropped connection itself, but a refused response (a proxy’s 502 while the server restarts) closes anEventSourcefor good, so the web client opens a new one after 3 seconds. - The UI hides admin-only actions from members. Loomarr is not meant to be exposed publicly.
Navigation
Members and admins get two separately authored navigations, not one list filtered by role: a member arrives to watch and ask for things, and greyed-out entries advertise a product they cannot use.
| Role | Items |
|---|---|
| admin | Home · Guide · Requests · Filler · People · Settings · Help |
| member | Home · Guide · Requests · Notifications · Help |
- Guide (
/guide, headed “Guide” like its nav item; #3413) is the single channels surface: a cross-channel time grid, with channel creation (describe → review → approve) as a header action. The old Channels and Suggest routes redirect to it. Desktop browsing uses the full content width. Programme and filler previews open beside the initiating block after a short hover or keyboard-focus intent delay. The pointer can enter the preview; it stays open while the block or preview is hovered or focused, closes on Escape or departure, and fits the viewport. Selection alone does not open a preview or imply focus. Programme cells retain their series/title text at narrow widths, clipping each line within the block rather than hiding its identity. Full names remain available through the accessible label and contextual preview; short filler segments keep their separate density treatment. Filler previews retain supplied clip names and kinds, without inventing metadata. The compact phone Guide and remote TV interaction remain separate adapters. - Requests (
/requests) is one surface for everyone (#1405). Its nav count is what waits on the viewer, the same number as its Needs you tab. - Home (
/dashboard, both roles) leads with what’s on, not machine state (#1659, #1822): a neutral channel-count line, then — only once something exists to show — the caller’s recently tuned channel, up to six currently scheduled live channels (“Your channels” and each one’s actual lifecycle when none currently has a block), actual Watching now sessions, typed Tonight highlights (premieres and marathons only), New this week, and each role’s own requests or channel ideas. A quiet household still gets the count and On now; a bare install gets “Your first channel starts here” and nothing else. Missing or failed artwork keeps its geometry and shows a restrained line motif with the channel’s monogram, never a broken-image glyph. Encoder, storage, service health and the restart control live in Settings → This server (admin-only), linked from Home’s footer, not duplicated on it. - People is admins managing other accounts. It reads its lists again on the admin-only
accessframe, sent after any stored change to an invitation, account, session or device, including a link redeemed or an email delivered behind the admin. Account (/account) is any user’s own password and sessions. Settings is a searchable task home, with Advanced settings as the raw-key escape hatch. Help renders the embedded help pages offline. - Global search (⌘K, or Ctrl K; the rail names the one the viewer’s platform uses) is a
design-system inline
Combobox(an always-open grouped list in a dialog) over/v1/search, channels and help.
Cross-view rules
- Nothing acquires or schedules without approval; the approval gate is visible where requests are reviewed, including bulk approve.
- Suggestion shows one calm status message, then an editable channel draft to review before approval
(
proposal-workflow.md). - The filler catalog is shared; each channel chooses from it in its own Filler section, where per-clip preferences are optional overrides, not setup.
Settings live in the app
Connections and integration settings are configured in the app, as in the *arr ecosystem, and the
environment can pin any of them (decision 0008). The
mechanics are in config-design.md.
API_TOKENandPLAYOUT_TOKENare generated on first boot and regenerable in Settings.- With
DATABASE_URLdefaulting to the SQLite volume, a baredocker runboots into the wizard. - Secrets in the database are masked after save, never logged, excluded from
/v1/setup/status, and backups are therefore secret material.
Operator first run
Every route sends an unbootstrapped install to the wizard, decided by the unauthenticated
GET /v1/setup/state. The steps:
- Bootstrap the owning admin (
POST /v1/setup/bootstrap); afterwards the step is read-only and names the owner. - Playout: Loomarr (default) or Tunarr, writing
playout.backend. Choosing Loomarr also requiresserver.public_urlon this step. - Location: one place combobox writing the installation country and, for a city, its place id
(
filler.home_place). - Connection checklist, live-testing each dependency with a fix hint and a docs deep link. It is
backed by
GET /v1/setup/statusand re-runnable from Settings for the life of the install. - Give Tunarr your library (Tunarr path only).
- Import media-server users (optional).
- Guided first channel from a template.
The playout choice shapes the wizard: the blocking checks are media_server on the internal path and
media_server plus tunarr on the Tunarr path. Steps a choice removes are hidden, not shown as
satisfied, and “Tunarr” appears nowhere before the Playout step. No wiring step may hold the wizard
hostage, and both one-click wiring actions also live in Settings → Connections.
Member first run
- A first-login intro explains the model: intent → proposal → approval → acquisition → a channel in the guide, which may start filler-heavy and improve as content lands.
- One-click channel templates (embedded JSON) prefill the channel request workspace; users edit before running. The workspace shows examples of constraints that work well.
- Members always see where a request is, from pending approval to live on a channel.
Tests that pin this
Formerly design.md §19.
- Onboarding:
GET /v1/setup/statusreports each integration’s pass or fail against mocks (including the Tunarr media-source-matches-library check); a Sonarr or RadarrTestwebhook with a minimal payload is acknowledged and flips the handshake check; a failing check carries an actionable hint and doc link. - Frontend: typed-client generation compiles; an e2e smoke of the approve flow runs against a
mocked backend; the SSE board updates on a simulated
available.