Skip to content

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 is no-store.
  • Types and hooks are generated by orval from the committed api/openapi.yaml; a contract change is a compile error. @loomarr/api re-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 an EventSource for 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.

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.

RoleItems
adminHome · Guide · Requests · Filler · People · Settings · Help
memberHome · 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 access frame, 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_TOKEN and PLAYOUT_TOKEN are generated on first boot and regenerable in Settings.
  • With DATABASE_URL defaulting to the SQLite volume, a bare docker run boots 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:

  1. Bootstrap the owning admin (POST /v1/setup/bootstrap); afterwards the step is read-only and names the owner.
  2. Playout: Loomarr (default) or Tunarr, writing playout.backend. Choosing Loomarr also requires server.public_url on this step.
  3. Location: one place combobox writing the installation country and, for a city, its place id (filler.home_place).
  4. Connection checklist, live-testing each dependency with a fix hint and a docs deep link. It is backed by GET /v1/setup/status and re-runnable from Settings for the life of the install.
  5. Give Tunarr your library (Tunarr path only).
  6. Import media-server users (optional).
  7. 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/status reports each integration’s pass or fail against mocks (including the Tunarr media-source-matches-library check); a Sonarr or Radarr Test webhook 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.