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 inreference/settings.md, and the package inventory ispackage-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.
| Doc | Owns | Old § | Now in |
|---|---|---|---|
| overview | scope, design envelope, ports, package-name traps, backend structure rules, HTTP API rules, concurrency rules | 1, 2, 7, 7.1, 14.1, 18 | here |
| dependencies | every dependency and bundled tool, with its reason | 14 | here |
| package-map | generated area index with the two main flows; each area’s packages and imports are on its own page in areas/ | 2 (map), 14.2 | here |
| acquisition | title identity, provisioning state machine, requesters, outbound client rules | 3, 4, 6 | here |
| library | media-server contract, media inventory, series episodes, search | 5 (inventory), 6, 7.2 | here |
| storage | one store with two backends, Postgres concurrency, retention, backup | 5, 16 (backup) | here |
| suggester | grounding, reference-backed Intent, explicit policy, providers, model selection and residency | 6 (reference source), 8, 8.1, 8.2 | here |
| proposal-workflow | approval ordering, Proposal Jobs, the Journey, failures, date interpretation, decision traces | 8 (execution, human-in-the-loop, traces) | here |
| scheduling | channels, lineups, strategies, reconcile and backfill, guide freshness, airing history, breaks, pods and mid-programme breaks | 5 (airing history), 9, 10 (breaks) | here |
| playout | the channel packager, backends, what is served, admission, playout status, Tunarr, Live TV wiring | 6 (Tunarr, Live TV), 9.1 | here |
| playback-clients | tuning, pause, Android TV | 9.1 (clients) | here |
| auth | identity, credentials, invitations, notifications, devices, roles, route authorization, SSO | 11 | here |
| web-ui | delivery, navigation, cross-view rules, the settings decision, first-run wizard, member first run | 12, 13 | here |
| deployment | restart in place, the image, Compose, upgrades, the job scheduler | 9.2, 16, 18.1 | here |
| observability | activity, diagnostics, correlation, client events, health, reports, metrics, discovery quality | 5 (activity, diagnostics tables), 17 | here |
| images | the image service | 22 | here |
| filler | catalog, sources, fetching, storage, pulls, lifecycle, media gates, media roles, conditioning, acquisition runs | 10 | here |
| filler-pipeline | the ingest pipeline, budgets, enrichment, Incoming, the catalog listing | 10 (V51b, V51d, V51e, V51g) | here |
| filler-structure | long-source quarantine, structure assessment, detection, auto-split, split review, composites | 10 (V34, V45, V51a, V67) | here |
| filler-classification | readiness, routing and accounting, operator surfaces, metadata, taxonomy, child screening, visual safety, the release report | 10 (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.
| # | Date | Decision |
|---|---|---|
| 0001 | 2026-07-13 | PostgreSQL and SQLite are both first-class stores |
| 0002 | 2026-07-13 | Code-first OpenAPI with Huma v2 |
| 0003 | 2026-07-13 | Search is federated; Loomarr builds no index |
| 0004 | 2026-07-13 | The LLM never supplies trusted identity |
| 0005 | 2026-07-13 | Proposals need human approval by default |
| 0006 | 2026-07-13 | Filler is its own pipeline, not the *arr path |
| 0007 | 2026-07-13 | Loomarr owns identity; every credential path lands on one users table |
| 0008 | 2026-07-14 | Settings live in the app; the environment pins |
| 0009 | 2026-07-25 | Loomarr plays out its own streams |
| 0010 | 2026-07-29 | Restart rebuilds in process, never exits |
| 0011 | 2026-07-30 | SSO is a credential path, not a provisioning path |
| 0012 | 2026-07-30 | Every route declares its role; anonymous is denied by default |
| 0013 | 2026-08-02 | Filler pulls are the approval gate; removal is a tombstone |
| 0014 | 2026-08-03 | Filler sources are one flat list, any number of folders and libraries |
| 0015 | 2026-08-03 | Filler sources fetch on their own |
| 0016 | 2026-08-03 | Clip identity is a content hash |
| 0017 | 2026-08-07 | Composites keep the parent; lineage is first-class |
| 0018 | 2026-08-09 | Ingest is one ordered, watchable pipeline |
| 0019 | 2026-08-09 | A stage’s budget is a per-clip rate |
| 0020 | 2026-08-09 | One content-addressed image service |
| 0021 | 2026-08-15 | Tuning is a latest-request-wins state machine |
| 0022 | 2026-08-17 | Pause is shared time-shift |
| 0023 | 2026-08-22 | Android TV is watching-first with one permanent app identity |
| 0024 | 2026-08-23 | React Native and Expo for client binaries |
| 0025 | 2026-09-02 | Three independently certified AI pillars |
| 0026 | 2026-09-02 | A specialized local model is an optional Suggester optimisation |
| 0027 | 2026-09-05 | Loomarr owns its media inventory; the library is an importer |
| 0028 | 2026-09-06 | Source evidence and playable media are separate assets |
| 0029 | 2026-09-06 | Compilation structure is assessed before children are materialized |
| 0030 | 2026-09-15 | Readiness is evidence-based; confidence never publishes |
| 0031 | 2026-09-26 | Tone curve: one default plus six selectable curves |
| 0032 | 2026-09-26 | 4K is a given; dynamic range is independent of resolution |
| 0033 | 2026-09-27 | Admission is one measured ledger |
| 0034 | 2026-09-27 | Mid-programme breaks on by default, with a per-channel off switch |
| 0035 | 2026-09-27 | CPU degradation ladder: never refuse on a slow CPU |
| 0036 | 2026-09-27 | The watermark is anchored to the measured active picture |
| 0037 | 2026-09-27 | One packager per (channel, format) |
| 0038 | 2026-09-27 | 1 s segments |
| 0039 | 2026-09-27 | Always transcode to one uniform channel output |
| 0040 | 2026-09-27 | Prepared media is withdrawn; nothing encodes until a viewer tunes |
| 0041 | 2026-09-27 | Ship ffmpeg 9 |
| 0042 | 2026-10-03 | The iPhone app has one permanent identity, selected only by its release build |
| 0043 | 2026-10-03 | A paired device acts with its approver’s role |
| 0044 | 2026-10-13 | The Apple TV app is its own App Store Connect app, selected only by its release build |
| 0045 | 2026-10-27 | Loomarr recommends curated filler sources, YouTube channels included |
| 0046 | 2026-11-03 | Loomarr scans its own media files; the media server keeps only sign-in and Live TV |
| 0047 | 2026-11-08 | Loomarr identifies media without Sonarr or Radarr, and keeps rich facts in queryable tables |
| 0048 | 2026-11-12 | A Ready clip Loomarr fetched keeps only its airing copy |
Future work that used to live in design.md §20 is tracked in #1576.