ersatztv/docs/domain-model.md

Domain model — glossary + concept map

Purpose: what the app IS — the entity chain and vocabulary an agent needs before touching scheduling, playout, or IPTV code. Update this doc in the same PR that changes any fact below.

The pipeline in one paragraph

Media libraries (Local/Plex/Jellyfin/Emby) are scanned into media items, which are grouped into collections/playlists/etc. Those groupings are arranged onto a playout by one of several scheduling engines (classic schedule, block/template calendar, sequential YAML, scripted, external-JSON) — a playout belongs to exactly one channel. Channels are exposed to IPTV clients (Jellyfin, Dispatcharr) as an M3U playlist + XMLTV guide, and streamed on demand via FFmpeg, all under the /iptv/* routes (ErsatzTV/Controllers/IptvController.cs).

Auto-tuning (#69) is a second, automatic-first channel-creation mode alongside the manual single-channel flow: it enumerates library metadata along an axis (TV Show / TV Genre / Movie Genre), previews the proposed channels (name, allocated number, item count) with no writes, and bulk-creates the selected ones via the #63 composite CreateChannelFromLineup primitive. Each generated channel is backed by a newly-created, live SmartCollection query, so it keeps tracking the library as it grows rather than freezing a static item list.

Entity chain sketch

Channel (1) ──< Playout (0..N per channel; ChannelPlayoutSource distinguishes Generated vs Mirror)
                  │
                  ├─ ScheduleKind: None/Classic/Block/Sequential/Scripted/ExternalJson
                  │     (PlayoutScheduleKind, ErsatzTV.Core/Domain/PlayoutScheduleKind.cs)
                  │
                  ├─ Classic:    ProgramSchedule ──< ProgramScheduleItem (TPT: One/Multiple/Flood/Duration)
                  │                 └─< ProgramScheduleAlternate (day/date-conditional alt schedule)
                  │
                  ├─ Block:      PlayoutTemplate (day/date-conditional, like ProgramScheduleAlternate)
                  │                 ──> Template ──< TemplateItem (time-of-day) ──> Block
                  │                                     Block ──< BlockItem (ordered collection items)
                  │                 PlayoutTemplate also optionally points at a DecoTemplate
                  │                 Playout can also point directly at a default Deco (DecoId)
                  │
                  ├─ Sequential: Playout.ScheduleFile (YAML, validated via the SPA's Schedule
                  │                 Validator / TroubleshootController)
                  │
                  ├─ Scripted:   ScriptedScheduleController-backed (not yet detailed here)
                  │
                  └─ ExternalJson: Playout.ScheduleFile (JSON)
                  Playout.Items = List<PlayoutItem> (the built, materialized schedule)
                  Playout.PlayoutHistory = rotation/rerun state (per Block for block playouts)

Deco/DecoTemplate are orthogonal to the schedule kind (mostly used with Block playouts but Playout.DecoId and Playout.Templates (PlayoutTemplate.DecoTemplateId) are independent FKs on Playout, not nested inside ProgramSchedule).

Glossary

Term	Meaning	Key entity	Edited at (SPA)
Classic playout	Schedule = ordered ProgramScheduleItem rows on a ProgramSchedule, played in sequence/loop. Alternate schedules let day-of-week/day-of-month/month/date-range conditions pick a different ProgramScheduleAlternate by Index order, first match wins; the row with the broadest/no conditions, placed last, acts as the catch-all default.	ProgramSchedule, ProgramScheduleItem, ProgramScheduleAlternate	/app/schedules
Block playout	A calendar of Templates assigned to times of day (TemplateItem.StartTime) and to a playout via PlayoutTemplate (day/date-conditional, same first-match/catch-all-last pattern as alternate schedules). Each Template is a day-grid of Blocks; each Block is an ordered list of BlockItems (collection/media/search references) with a Minutes duration and a BlockStopScheduling rule (AfterDurationEnd vs BeforeDurationEnd).	Template, TemplateItem, Block, BlockItem, PlayoutTemplate	/app/templates, /app/blocks, /app/playouts/{id}/templates
Sequential playout	Driven by a YAML file (Playout.ScheduleFile); validated via the Schedule Validator screen.	Playout.ScheduleFile	/app/troubleshooting/yaml (validate only; file itself is server-side)
Scripted playout	PlayoutScheduleKind.Scripted; backed by ScriptedScheduleController.	—	—
External-JSON playout	PlayoutScheduleKind.ExternalJson = 20; JSON-driven, same shape idea as Sequential but JSON instead of YAML.	Playout.ScheduleFile	—
Reshuffle	Playout.Seed (the master shuffle seed) is surfaced on the playout list + detail API so the SPA can show it; a per-playout Reshuffle action reseeds and rebuilds via POST /api/v1/playouts/{id}/reshuffle (enqueues BuildPlayout(id, PlayoutBuildMode.Reset)), distinct from reset-all's Refresh mode for Classic.	Playout.Seed	/app/playouts
Deco	Per-playout "decoration": one of 4 independently-modal sections — watermark, graphics elements, default filler, dead-air fallback — plus break content. Each mode section is Inherit/Disable/Override/Merge (DecoMode). Can attach directly to a Block playout via Playout.DecoId.	Deco, DecoGroup, DecoBreakContent	/app/decos
DecoTemplate	Time-of-day (DecoTemplateItem.StartTime/EndTime) calendar of Decos, assigned to a playout via PlayoutTemplate.DecoTemplateId (same row as the Block-template assignment — one PlayoutTemplate entry carries both a Template and an optional DecoTemplate).	DecoTemplate, DecoTemplateItem, DecoTemplateGroup	/app/deco-templates
Default deco vs deco templates	Playout.DecoId = one static deco for the whole playout; PlayoutTemplate.DecoTemplateId = a time-varying deco schedule. Both are optional and independent.	Playout, PlayoutTemplate	/app/playouts/{id}/templates
FillerPreset	A reusable filler definition: FillerKind (PreRoll/MidRoll/PostRoll/Tail/Fallback; also GuideMode=99, DecoDefault=100) × FillerMode (None/Duration/Count/Pad/RandomCount) over a collection/media-item/multi-collection/smart-collection/playlist source, with an optional Expression (NCalc). Referenced from ProgramScheduleItem (Pre/Mid/Post/Tail/FallbackFillerId) and Channel.FallbackFillerId.	FillerPreset, FillerKind, FillerMode	/app/filler-presets
Watermark	ChannelWatermark image overlay; attached at channel, schedule-item, block-item, deco, or playout-item level with position/size/opacity.	ChannelWatermark, DecoWatermark, BlockItemWatermark, ProgramScheduleItemWatermark	/app/watermarks
Collection	Manual list of media items (CollectionItem).	Collection	/app/collections
SmartCollection	Saved search — a Query string, no static item list.	SmartCollection	/app/collections
MultiCollection	Combines multiple Collections and/or SmartCollections (with grouping via MultiCollectionItem/MultiCollectionSmartItem).	MultiCollection	/app/multi-collections (#151)
RerunCollection	One source (collection/media item/multi/smart) with separate FirstRunPlaybackOrder vs RerunPlaybackOrder.	RerunCollection	/app/rerun-collections (#152)
Playlist / PlaylistGroup	Ordered PlaylistItems; IsSystem flag marks built-in/non-deletable playlists and groups.	Playlist, PlaylistGroup, PlaylistItem	/app/playlists
Media kinds	CollectionType enum distinguishes container kinds (Collection/TelevisionShow/TelevisionSeason/Artist/MultiCollection/SmartCollection/Playlist/RerunFirstRun/RerunRerun/SearchQuery) from leaf media kinds (Movie/Episode/MusicVideo/OtherVideo/Song/Image/RemoteStream) plus synthetic FakeCollection/FakePlaylistItem. Concrete media entities: Movie, Show/Season/Episode, Artist/MusicVideo/Song, OtherVideo, Image, RemoteStream (ErsatzTV.Core/Domain/MediaItem/).	MediaItem subclasses	/app/media?kind=...
Library / LibraryPath / LibraryFolder	Library (abstract; Local/Plex/Jellyfin/Emby subclasses) owns one or more LibraryPaths (scan roots); each path has a LibraryFolder tree used for browsing and image-folder duration metadata.	Library, LibraryPath, LibraryFolder	/app/libraries (hub: list + scan); /app/libraries/local/{id} (/new) for local library name/media-kind/path CRUD + move-path (#202)
Media source kind	MediaSourceKind: Local/Plex/Jellyfin/Emby — the origin server type for a Library.	MediaSourceKind	/app/libraries (hub); connect/edit/disconnect and per-source library-sync + path-replacements now live at /app/libraries/{plex|jellyfin|emby} (+ /connection, /{id}/sync, /{id}/path-replacements) — #202, previously Blazor-only
MediaItemState	Health flag on a media item: Normal/FileNotFound/Unavailable/RemoteOnly. Drives the Trash screen.	MediaItemState	/app/trash
PlayoutItem	One materialized, built entry in a playout's timeline (the actual thing that will play at a given time).	PlayoutItem	(generated, not directly edited)
PlayoutHistory	Rotation/rerun bookkeeping per block (BlockId) + collection Key/ChildKey, used by block-playout schedulers to avoid repeats; inspectable via Troubleshooting.	PlayoutHistory	/app/troubleshooting/blocks
Channel concepts	Number (validated by Channel.NumberValidator regex), Group, PlayoutSource (Generated/Mirror; Mirror channels relay another channel via MirrorSourceChannelId+PlayoutOffset), PlayoutMode (Continuous/OnDemand), TranscodeMode (OnDemand only, today), IdleBehavior (StopOnDisconnect/KeepRunning), StreamingMode (TransportStream/HttpLiveStreamingDirect/HttpLiveStreamingSegmenter/TransportStreamHybrid).	Channel	/app/channels, /app/edit-channel/{id}, /app/new-channel
Guide / EPG (XMLTV)	Per-channel programme guide generated from playout items; channels with ShowInEpg=false are excluded.	GetChannelGuideHandler	/app/guide (viewer); settings at /app/settings/xmltv
M3U	The channel lineup playlist Jellyfin/Dispatcharr consume.	ChannelPlaylist.ToM3U()	—
IPTV base URL	Optional advertised base URL for the IPTV surface (#340). Stored as a single ConfigElement (ConfigElementKey.IptvBaseUrl, key iptv.base_url, no EF migration); when set, GetChannelPlaylistHandler (M3U) and GetChannelGuideHandler (XMLTV) pin their absolute URLs to its scheme/host/base instead of the request Host (blank/invalid → request-derived). Not applied to HDHomeRun; distinct from ETV_BASE_URL. Parsed by ErsatzTV.Core/Iptv/AdvertisedBaseUrl.cs.	ConfigElementKey.IptvBaseUrl	/app/settings → IPTV (GET/PUT /api/v1/settings/iptv)
Aggregate Version	Optimistic-concurrency token (issue #253): a plain int Version on the 9 replace-all roots — ProgramSchedule, Block, Template, DecoTemplate, Playlist, Collection, Playout, MultiCollection, RerunCollection — implementing IVersionedAggregate, EF-mapped .IsConcurrencyToken(). Surfaced as a strong ETag on the aggregate's GET and checked against If-Match on the PUT (mismatch → 412). See api-conventions.md §7a.	IVersionedAggregate	(not user-edited)

Where things are edited (SPA routes)

Primary nav: /app (dashboard), /app/channels, /app/new-channel, /app/guide, /app/schedules, /app/blocks, /app/templates, /app/decos, /app/deco-templates, /app/playouts (+ sub-paths /app/playouts/{id}/alternate-schedules, /app/playouts/{id}/templates).

Media nav: /app/media (generic kind-filtered browse, ?kind=movies|shows|artists|music-videos| other-videos|remote-streams|images), /app/search, /app/trash, /app/collections (manual + smart), /app/multi-collections (#151), /app/rerun-collections (#152), /app/filler-presets, /app/libraries (+ sub-paths, see below), /app/trakt-lists.

Media sources / libraries (#202, 2026-07-11): /app/libraries is an allowSubPaths route (LibrariesRouteScreen, App-owned popstate — see spa-conventions.md §2/§8). The hub itself lists sources/libraries and triggers scans; connecting/editing/removing a source and its libraries now happens at:

• /app/libraries/local/new, /app/libraries/local/{id} — LocalLibraryEditScreen: name, media-kind (create-only), path add/move/delete.
• /app/libraries/plex — PlexSourceScreen: OAuth pin-flow sign-in/fix-credentials/sign-out.
• /app/libraries/{jellyfin|emby} — RemoteSourceScreen; /app/libraries/{jellyfin|emby}/connection — RemoteConnectionEditScreen (address + api-key, key never displayed once set).
• /app/libraries/{plex|jellyfin|emby}/{id}/sync — RemoteLibrariesEditScreen (per-library sync toggle); /app/libraries/{plex|jellyfin|emby}/{id}/path-replacements — PathReplacementsEditScreen.

These replace the Blazor /media/sources/{local,plex,jellyfin,emby}/... pages over the new /api/v1/libraries/local/* and /api/v1/media-sources/{plex|jellyfin|emby}/* write endpoints — see docs/blazor-route-parity.md Section 2 for the full per-route mapping.

System nav: /app/settings (sub-tabs: streaming/system/logging/playout/scanner/general/xmltv — all mapped 1:1 from legacy /settings/* Blazor routes — plus a new IPTV section, #340, that edits the advertised IPTV base URL via GET/PUT /api/v1/settings/iptv), /app/logs, /app/troubleshooting (+ /app/troubleshooting/blocks block-playout history, /app/troubleshooting/yaml sequential-schedule validator; playback troubleshooting still gated on API #145), /app/ffmpeg-profiles, /app/watermarks.

/app/edit-channel/{id} (edit) is reached from the channels table, not the primary sidebar nav. Per-item media detail pages and the image-folder browser (MediaDetailScreen's MovieDetailScreen/ShowDetailScreen/SeasonDetailScreen/ArtistDetailScreen, ImageBrowserScreen) landed via #141 (PR #183) at /app/media/{movies|shows|seasons|artists}/{id} and /app/media/images/browser. Multi-collection (#151), rerun-collection (#152), and playlist (#153) editors now live in the SPA at /app/multi-collections, /app/rerun-collections, and /app/playlists. See docs/blazor-route-parity.md for the full route-by-route tracker.

Key handler / file locations

• Classic scheduling engine: ErsatzTV.Core/Scheduling/PlayoutBuilder.cs, PlayoutModeSchedulerBase.cs (+ One/Multiple/Flood/Duration variants), AlternateScheduleSelector.cs (first-match-wins alternate/template selection).
• Block scheduling engine: ErsatzTV.Core/Scheduling/PlayoutModeBlock.cs.
• Build entry point: ErsatzTV.Application/Playouts/Commands/BuildPlayoutHandler.cs.
• M3U generation: ErsatzTV.Core/Iptv/ChannelPlaylist.cs → ToM3U().
• XMLTV generation: ErsatzTV.Application/Channels/Queries/GetChannelGuideHandler.cs.
• Streaming / IPTV routes: ErsatzTV/Controllers/IptvController.cs (/iptv/channels.m3u, /iptv/xmltv.xml, /iptv/channel/{number}.ts, /iptv/session/{number}/hls.m3u8, HDHR routes, logos).