Skip to content

Loomarr system design

Status: Pointer file. This document was split into docs/design/ (#779), which is now the source of truth for how the system works and why. Each numbered section below keeps its heading so old links and design.md §N citations still resolve, and says where its content went. The last full version is design.md at 8031a52f.

Three release and testing passages (browser certification layering and Android TV distribution under §9.1, the gate composition and CI selection under §19, and image runtime certification under §22) are still here until #1572 moves them: testing and certification to docs/contributing/testing.md and docs/contributing/releasing.md, Android TV distribution to project/android-release.md. Until then they remain current; amend them in the same PR as the behaviour they describe. Add nothing else to this file.

Audience: Builders and coding agents. User-facing instructions live under Get started and docs/guides/. CONTEXT.md owns vocabulary and PROGRESS.md owns work status.


1. Purpose

Moved to design/overview.md.

2. Architecture

Moved to design/overview.md; the generated package map is design/package-map.md.


3. Provisioner domain model

Moved to design/acquisition.md.

4. Provisioning state machine

Moved to design/acquisition.md.

5. Persistence — Postgres and SQLite

The store, retention, PostgreSQL concurrency and the SQLite → PostgreSQL migration moved to design/storage.md; the media inventory and series episodes moved to design/library.md; airing history moved to design/scheduling.md; the activity and diagnostic evidence tables moved to design/observability.md.


6. External contracts

Client resilience rules and the requesters moved to design/acquisition.md; the Emby and Jellyfin contract moved to design/library.md; the Tunarr programmer and Live TV wiring moved to design/playout.md.


7. HTTP API

The API reference is the OpenAPI spec (api/openapi.yaml, served at /docs); the hand-kept route table that stood here was deleted in #779. §7.1’s rules moved to design/overview.md; route authorization is §11.

7.2 Search (federated, no index)

Moved to design/library.md.


8. Suggester (AI suggestion engine)

Grounding, reference-backed Intent, providers, §8.1 model selection and §8.2 model residency moved to design/suggester.md. The specialized local model experiment is archived in project/design-archive-2026-09/. Approval, Proposal execution and the decision traces moved to design/proposal-workflow.md.


9. Scheduler / lineup builder — the point of the app

Moved to design/scheduling.md, including guide freshness, backfill and “what does not change” between playout backends.


9.1 Playout backends — Loomarr serves its own streams

The channel packager, backend selection, what internal playout serves, admission and playout status moved to design/playout.md. The founding reversal is decision 0009. Tuning, pause and the Android TV client moved to design/playback-clients.md. Playback certification moved to contributing/testing.md, and the Android TV artifact and build contract to project/android-release.md.

9.2 Restarting in place (V13)

Moved to design/deployment.md, with decision 0010.

10. Commercials & filler

Moved to four docs: design/filler.md (catalog, sources, fetching, storage, pulls, lifecycle, media gates, media roles, conditioning, acquisition runs), design/filler-pipeline.md (the ingest pipeline and budgets), design/filler-structure.md (structure assessment, splitting, composites) and design/filler-classification.md (tagging, taxonomy, readiness, screening, the release report). Decisions 0006, 0013–0019 and 0028–0030.


11. Users, authentication & permissions

Moved to design/auth.md, with decisions 0007, 0011 and 0012. The auth negatives in §19 stay there until §19 is split.


12. Web UI

Moved to design/web-ui.md. Per-view descriptions were deleted; the mocks and components own them.


13. Onboarding & documentation

The settings decision, operator wizard and member first run moved to design/web-ui.md, with decision 0008. The documentation set is described by docs/README.md and the contributor docs, not here.


14. Technology stack (decided)

Moved to design/dependencies.md; §14.1’s structure rules moved to design/overview.md. The suggester certification rules that followed §14.1 moved to design/suggester.md (discovery feedback and evaluation) and the archive (suggester-certification.md).

14.2 The package map

Moved to design/package-map.md. The hand-kept role table that stood here was a stale second copy of the generated map and was deleted in #779.

15. Configuration — layered settings

Moved to config-design.md, with decision 0008. The settings table was deleted: the generated settings reference is the key reference.


16. Deployment (Docker)

The image, Compose and upgrades moved to design/deployment.md; backup and restore to design/storage.md. The operator runbook and Compose listing were deleted: the wizard, docs/guides/install-docker.md and docker/compose.yaml own them.

17. Observability

Moved to design/observability.md.

18. Concurrency & correctness

Moved to design/overview.md.

18.1 The job scheduler — named, tunable, on-demand background work

Moved to design/deployment.md.

19. Testing strategy

Each subsystem’s test obligations moved to a “Tests that pin this” section in its doc under design/. Gate composition and CI selection moved to contributing/testing.md (make verify, the layers) and contributing/ci.md (selection, the merge queue, sharding, ci-ok).


20. Open questions & follow-ons

Moved to #1576. Plans live in issues, not in this document.

21. Build plan for coding agents (phased, verifiable)

Deleted in #779: the phase plan shipped, and git history keeps it.


22. Image service — one pipeline for every image

Moved to design/images.md, with decision 0020. The data model, width ladders and job list were deleted: the migrations, the code and the scheduler registry own them. The frontend contract moved to frontend-design.md. Runtime certification (make image-cert, make image-bench) moved to contributing/releasing.md.