Skip to content

Package map

The packages under internal/, grouped into a handful of areas. New here? Read Start here first: it says what each area is for and traces the two main flows through them. Each area’s page lists its packages, what each is for and what it imports. The block below and the area pages in areas/ are generated by make arch-docs from the area table in cmd/arch-docs/areas.go, each package’s doc comment and its exact imports, and CI fails when they drift (TestArchDocs_NoDrift) or when a package has no area (TestArchDocs_AreasCoverEveryPackage). Edit the package doc comment or the area table, not these pages.

For the rules the layering follows, and the package names that are easy to confuse, see the design index.

Start here

The packages under internal/ group into the areas below. Each area has its own generated page listing its packages, what each one imports, how many packages import it, and which other areas it reaches into (counted as package-to-package imports), each with the reason. The area table lives in cmd/arch-docs/areas.go; a new package must be added to one area before it merges, and a new import into another area must be declared there with its reason. A reason ending “until …” is an import that should go.

Library

What the household owns and wants. Talks to the media server (Emby or Jellyfin), keeps Loomarr’s own record of every film and episode, looks titles up on TMDB, and asks Sonarr or Radarr to fetch a title the household does not have yet. The metadata providers decide which source’s facts about a file win.

Media

Shared tools for looking at and working on media files: reading what a file’s header says, measuring keyframes and loudness, running ffmpeg and ffprobe safely, picking the GPU encoder, and the one pipeline every image goes through. It also holds the checks that judge a clip’s picture, sound and level, and whether two adverts are the same one.

Channels

Channels and what they play. A channel’s lineup becomes an ordered schedule, and the reconcile engine keeps each channel’s programming current for whichever backend plays it. Operator edits and approved proposals each have one write path. Self-updating channels are re-curated here, Home’s channel ideas come from here, and so does who is watching now.

Proposals

Turning “I want a channel that feels like X” into a lineup a person can approve. The suggester checks every title against the real library and catalog, the workflow tracks each request through to the household’s first channel, and the outlook explains a pending proposal before anyone approves it. Accepting a proposal, by a person’s approval or the auto-approve grant within its pending-acquisition quota, is its own package. The quality and planner-reference packages measure how good the suggestions are.

Playout

Getting a channel onto a TV. Loomarr’s own streaming engine stitches a channel into one continuous stream and burns in the channel’s logo; Tunarr is the other backend that can play a channel. The Live TV wiring and the backend transition publish channels to the media server, LAN discovery lets TV apps find Loomarr, and the bench measures the pipeline on real hardware.

Filler

Commercials, bumpers and station IDs. Sources such as YouTube, archive.org and local folders are listed and fetched; every clip is checked for safety, structure and defects, then admitted or refused; admitted clips are catalogued with their tags and the TV stations they name; and the catalog is assembled into the pods that fill a channel’s breaks.

People

Who may use Loomarr and how they are reached: sign-in sessions, invitations, password recovery, contact addresses and notifications, plus the encryption of the secrets Loomarr keeps in its database.

Platform

The ground everything else stands on: the store and its two databases, settings and start-up configuration, background jobs and scheduled clean-up, the activity feed and diagnostics, metrics, the outbound HTTP client, the event bus, disk-space reservations, the language-model and OpenRouter clients, the embedded web app, release tooling, and small shared vocabularies such as holidays, language codes, the audience rating ladder and whole-word text matching.

Edge

Where the outside world comes in. The api package is Loomarr’s HTTP surface, and app is the composition root that builds every other area and hands them to it. api/httpcore is the plumbing every part of the HTTP surface shares: problem responses, request ids, roles and the route-role marker. app/playoutresolve is the composition root’s playout wiring: it reads the stores and settings that playout must not know about.

Test support

Code that exists for tests and never ships in the server: the shared test doubles and fixtures, the store’s SQLite and Postgres test databases, the invented demo library and the TMDB stand-in it and the tests share, the end-to-end integration journeys, and the evaluation harness that runs only under its own build tag.

Two flows, end to end

From a request to Live TV

A member asks for a channel through api. proposals/workflow turns the request into a durable Proposal Job and runs proposals/suggest, which grounds each title through library/titlesearch(the library, library/tmdb and the clip catalog) and proposals/webreference, using a model from platform/llm, and returns the values in proposals. When a person approves it, channels/approval plans the channel and channels/edit writes it through platform/store; any title the household lacks becomes a library/provision record that library/provisionbackstop hands to library/requester for Sonarr or Radarr. channels/schedule turns the approved lineup and what is actually available into ordered programming, and the channels reconcile engine keeps that current for the channel’s backend: either Loomarr’s own playout engine, whose playout/packager stitches one continuous stream, or playout/tunarr. playout/livetvpublish registers the playlist and guide with the media server’s Live TV through library/mediaserver, and when the household changes backend, playout/backendtransition prepares the new one fully before publishing it to the media server.

From a filler source to a break

An operator registers a source; filler/source lists what it offers, with filler/source/youtube and filler/source/archive as the remote kinds. filler/fetch downloads each pulled clip into the drop folder, and filler drains that folder into the clip folder, while filler/records records the sources, pulls and acquisition runs. Each clip is then checked: filler/screening for what it says and shows, and whether it is safe to air, filler/structure/assessment for long reels that need splitting, and filler/defectfloor for picture and sound defects. A clip that passes its checks enters the catalog, whose values are filler/clips, whose tags are filler/taxonomy, and which platform/store/clipstore persists. When channels/schedule leaves a break in a channel’s programming, the channels engine asks filler for a pod that fits it, and playout plays the pod as part of the stream.

Dependency spine

Packages imported by 5 or more others, and their dependencies within the spine. Everything else in the tree sits on top of these packages.

PackageDepends on
api/httpcorechannels/schedule, channels/viewing, filler/source, media/images, platform/rating, platform/settings, platform/store/channelstore, platform/store/identitystore, playout
channelschannels/schedule, filler/clips, filler/language, filler/pod, library/inventory, library/provision, platform/jobs, platform/rating, platform/settings, platform/store, platform/store/activitystore, platform/store/channeldatastore, platform/store/channelstore, platform/store/librarystore, platform/store/proposalstore, playout, playout/tunarr
channels/schedulelibrary/inventory, library/provision, platform/holidayvocab, platform/rating
channels/viewingplatform/store, platform/store/channelstore
fillerfiller/acquisition, filler/asset, filler/cliplibrary, filler/clips, filler/language, filler/pipelinestate, filler/pod, filler/research, filler/split, filler/structure, filler/structure/window, filler/taxonomy, media/creative, media/defects, media/encode, media/tools, platform/diagnostics, platform/httpx, platform/llm, platform/storagegovernor, platform/store/clipstore
filler/acquisitionfiller/cliplibrary, filler/clips, filler/language, filler/pipelinestate, filler/pod, filler/source, filler/split
filler/assetfiller/clips, filler/split, media/tools, platform/storagegovernor
filler/cliplibraryfiller/asset, filler/clips, filler/pod, filler/split, media/bgexec, media/tools, platform/storagegovernor
filler/clips—
filler/defectfloorfiller, filler/asset, filler/cliplibrary, filler/clips, filler/pipelinestate, media/creative, media/defects, media/tools, platform/llm, platform/store/clipstore
filler/enrichmentfiller/station, filler/taxonomy, platform/llm
filler/fetchfiller/acquisition, filler/asset, filler/cliplibrary, filler/source, media/bgexec, platform/storagegovernor
filler/languagemedia/bgexec, media/tools
filler/pipelinestate—
filler/podchannels/schedule, filler/clips, filler/language
filler/recordsfiller, filler/acquisition, filler/asset, filler/clips, filler/enrichment, filler/pipelinestate, filler/pod, filler/research, filler/source, filler/split, filler/structure, filler/structure/window, platform/store, platform/store/clipstore, platform/store/storedb
filler/researchplatform/llm
filler/source—
filler/splitfiller/clips, filler/structure, media/tools
filler/stationfiller/research
filler/structure—
filler/structure/windowfiller/structure
filler/taxonomy—
library/inventory—
library/mediaserverplatform/httpx, platform/metrics
library/metadataprovider—
library/provision—
library/titlesearchlibrary/mediaserver, library/provision, platform/store/librarystore
library/tmdblibrary/provision, library/titlesearch, platform/httpx, platform/metrics
media/bgexec—
media/creative—
media/defects—
media/encodeplatform/config
media/imagesplatform/httpx, platform/jobs, platform/settings, platform/store/activitystore
media/toolsmedia/bgexec, media/creative, media/defects, media/encode, platform/diagnostics
people/accesspeople/contact
people/contact—
people/notificationspeople/secretprotection, platform/httpx
people/secretprotectionplatform/config
platform/activityplatform/store/activitystore
platform/buildinfo—
platform/config—
platform/diagnosticsplatform/storagegovernor
platform/holidayvocab—
platform/httpxplatform/metrics
platform/jobsplatform/store
platform/llmplatform/httpx, platform/metrics
platform/metricslibrary/provision
platform/rating—
platform/settingslibrary/mediaserver, platform/buildinfo, platform/config, platform/httpx
platform/storagegovernor—
platform/storechannels/schedule, filler/clips, filler/station, filler/taxonomy, library/inventory, library/provision, media/creative, media/defects, people/access, people/contact, people/notifications, people/secretprotection, platform/diagnostics, platform/holidayvocab, platform/store/activitystore, platform/store/channeldatastore, platform/store/channelstore, platform/store/clipstore, platform/store/identitystore, platform/store/librarystore, platform/store/proposalstore, platform/store/storedb, proposals, proposals/quality
platform/store/activitystoreplatform/store/storedb
platform/store/channeldatastorelibrary/provision, platform/store/storedb
platform/store/channelstorechannels/schedule, library/provision, platform/store/storedb
platform/store/clipstorechannels/schedule, filler/clips, filler/station, filler/taxonomy, media/creative, media/defects, platform/holidayvocab, platform/store/storedb
platform/store/identitystorepeople/access, people/contact, people/notifications, platform/store/storedb
platform/store/librarystoreplatform/store/storedb
platform/store/proposalstoreplatform/store/channelstore, platform/store/storedb, proposals
platform/store/storedb—
playoutchannels/schedule, library/provision, media/encode, platform/diagnostics
playout/tunarrchannels/schedule, platform/httpx, platform/metrics
proposalschannels/schedule, library/provision, platform/storagegovernor
proposals/acceptlibrary/provision, library/titlesearch, platform/holidayvocab, platform/rating, platform/store, platform/store/channelstore, platform/store/proposalstore, proposals, proposals/suggest
proposals/qualitylibrary/provision
proposals/suggestchannels/schedule, library/provision, library/titlesearch, library/tmdb, platform/holidayvocab, platform/llm, platform/rating, platform/store/channelstore, platform/store/proposalstore, proposals, proposals/quality

How the area pages are made

Generated recursively from each package’s own doc comment and exact internal imports, using full paths below internal/, so they cannot drift from the code the way a hand-maintained list does. Sizes are deliberately absent — they change on nearly every commit, which would make the drift check red by default and train everyone to regenerate without reading.