Skip to content

Loomarr design

Loomarr turns “I want a channel that feels like X” into a running virtual TV channel and keeps it populated as content comes and goes. The loop is intent → grounded proposal → acquire what is missing → build the schedule → play it out → keep it filled, sized for one household: about 100k library items, up to 50 channels, 20 users, 10k filler clips and one media server.

This directory describes how the system works now and why the lasting decisions were made. It replaced the single docs/design.md (#779), which is now a pointer file; its last full version stays readable by permalink. Three release and testing passages stay in design.md until #1572 moves them to docs/contributing/ and project/android-release.md.

How to use these docs

  • Current behaviour only. A subsystem doc says what the code does today. Amend it in the same PR as the behaviour change, before the code.
  • Decisions are records. When a change settles a question whose reason will still matter, add a short record under decisions/ (context, decision, consequences, what it supersedes). Records are append-only: a later decision supersedes an earlier one, and neither is rewritten.
  • Plans live in issues and milestones, not here. Link the issue instead of describing the plan.
  • Generated facts stay generated. The HTTP API reference is the OpenAPI spec (api/openapi.yaml, served at /docs), settings are in reference/settings.md, and the package inventory is package-map.md. Do not restate them in prose.
  • Vocabulary is defined in CONTEXT.md. Work status lives in GitHub issues.
  • New to the backend? Read Start here in the package map first. It groups the packages under internal/ into areas in plain words and traces a channel request and a commercial end to end.

Subsystems

The Old § column maps the §N references in code comments to the doc that now owns them.

DocOwnsOld §Now in
overviewscope, design envelope, ports, package-name traps, backend structure rules, HTTP API rules, concurrency rules1, 2, 7, 7.1, 14.1, 18here
dependenciesevery dependency and bundled tool, with its reason14here
package-mapgenerated area index with the two main flows; each area’s packages and imports are on its own page in areas/2 (map), 14.2here
acquisitiontitle identity, provisioning state machine, requesters, outbound client rules3, 4, 6here
librarymedia-server contract, media inventory, series episodes, search5 (inventory), 6, 7.2here
storageone store with two backends, Postgres concurrency, retention, backup5, 16 (backup)here
suggestergrounding, reference-backed Intent, explicit policy, providers, model selection and residency6 (reference source), 8, 8.1, 8.2here
proposal-workflowapproval ordering, Proposal Jobs, the Journey, failures, date interpretation, decision traces8 (execution, human-in-the-loop, traces)here
schedulingchannels, lineups, strategies, reconcile and backfill, guide freshness, airing history, breaks, pods and mid-programme breaks5 (airing history), 9, 10 (breaks)here
playoutthe channel packager, backends, what is served, admission, playout status, Tunarr, Live TV wiring6 (Tunarr, Live TV), 9.1here
playback-clientstuning, pause, Android TV9.1 (clients)here
authidentity, credentials, invitations, notifications, devices, roles, route authorization, SSO11here
web-uidelivery, navigation, cross-view rules, the settings decision, first-run wizard, member first run12, 13here
deploymentrestart in place, the image, Compose, upgrades, the job scheduler9.2, 16, 18.1here
observabilityactivity, diagnostics, correlation, client events, health, reports, metrics, discovery quality5 (activity, diagnostics tables), 17here
imagesthe image service22here
fillercatalog, sources, fetching, storage, pulls, lifecycle, media gates, media roles, conditioning, acquisition runs10here
filler-pipelinethe ingest pipeline, budgets, enrichment, Incoming, the catalog listing10 (V51b, V51d, V51e, V51g)here
filler-structurelong-source quarantine, structure assessment, detection, auto-split, split review, composites10 (V34, V45, V51a, V67)here
filler-classificationreadiness, routing and accounting, operator surfaces, metadata, taxonomy, child screening, visual safety, the release report10 (V38, V44, V45, V61–V63, V67, V68)here

Settings (§15) belong to config-design.md. Scheduling heuristics belong to programming-design.md, and the client architecture to frontend-design.md.

Decisions

Records are added under decisions/ as each subsystem moves. Numbers were assigned in date order when the map was approved on #779, so gaps close as the remaining records are written.

#DateDecision
00012026-07-13PostgreSQL and SQLite are both first-class stores
00022026-07-13Code-first OpenAPI with Huma v2
00032026-07-13Search is federated; Loomarr builds no index
00042026-07-13The LLM never supplies trusted identity
00052026-07-13Proposals need human approval by default
00062026-07-13Filler is its own pipeline, not the *arr path
00072026-07-13Loomarr owns identity; every credential path lands on one users table
00082026-07-14Settings live in the app; the environment pins
00092026-07-25Loomarr plays out its own streams
00102026-07-29Restart rebuilds in process, never exits
00112026-07-30SSO is a credential path, not a provisioning path
00122026-07-30Every route declares its role; anonymous is denied by default
00132026-08-02Filler pulls are the approval gate; removal is a tombstone
00142026-08-03Filler sources are one flat list, any number of folders and libraries
00152026-08-03Filler sources fetch on their own
00162026-08-03Clip identity is a content hash
00172026-08-07Composites keep the parent; lineage is first-class
00182026-08-09Ingest is one ordered, watchable pipeline
00192026-08-09A stage’s budget is a per-clip rate
00202026-08-09One content-addressed image service
00212026-08-15Tuning is a latest-request-wins state machine
00222026-08-17Pause is shared time-shift
00232026-08-22Android TV is watching-first with one permanent app identity
00242026-08-23React Native and Expo for client binaries
00252026-09-02Three independently certified AI pillars
00262026-09-02A specialized local model is an optional Suggester optimisation
00272026-09-05Loomarr owns its media inventory; the library is an importer
00282026-09-06Source evidence and playable media are separate assets
00292026-09-06Compilation structure is assessed before children are materialized
00302026-09-15Readiness is evidence-based; confidence never publishes
00312026-09-26Tone curve: one default plus six selectable curves
00322026-09-264K is a given; dynamic range is independent of resolution
00332026-09-27Admission is one measured ledger
00342026-09-27Mid-programme breaks on by default, with a per-channel off switch
00352026-09-27CPU degradation ladder: never refuse on a slow CPU
00362026-09-27The watermark is anchored to the measured active picture
00372026-09-27One packager per (channel, format)
00382026-09-271 s segments
00392026-09-27Always transcode to one uniform channel output
00402026-09-27Prepared media is withdrawn; nothing encodes until a viewer tunes
00412026-09-27Ship ffmpeg 9
00422026-10-03The iPhone app has one permanent identity, selected only by its release build
00432026-10-03A paired device acts with its approver’s role
00442026-10-13The Apple TV app is its own App Store Connect app, selected only by its release build
00452026-10-27Loomarr recommends curated filler sources, YouTube channels included
00462026-11-03Loomarr scans its own media files; the media server keeps only sign-in and Live TV
00472026-11-08Loomarr identifies media without Sonarr or Radarr, and keeps rich facts in queryable tables
00482026-11-12A Ready clip Loomarr fetched keeps only its airing copy

Future work that used to live in design.md §20 is tracked in #1576.