timothy/ersatztv
1
0
Fork 0
Code Issues 5 Pull Requests Actions Packages Projects Releases Wiki Activity

Missing architecture docs: channel management, M3U generation, logo fixes #6

New Issue
Closed
opened 2026-03-17 21:26:43 +01:00 by timothy · 1 comment
timothy commented 2026-03-17 21:26:43 +01:00
Owner
Copy Link

Finding (adversarial docs review 2026-03-17)

The ersatztv project has good CLAUDE.md and MEMORY.md coverage for the tech stack and CI/CD, but no design/architecture documentation for the application-level concerns that matter most for maintaining this fork:

What's missing

  1. Channel architecture: How channels are defined, what content sources feed them, scheduling logic. The 29 (or 31?) channels are listed in Docker/ErsatzTV.md in server-management docs but the design decisions behind them aren't captured.

  2. M3U/XMLTV generation: How playlists are built, the tvg-logo URL issue (Gitea issue #1), and how Jellyfin consumes the output. This is the core integration point.

  3. Logo fix design: The logo watermark/fix script is documented in server-management's Docker/ErsatzTV.md but the reasoning and implementation approach aren't in this repo.

  4. Fork maintenance strategy: Upstream is archived (Feb 2026). How do we handle:

    • Security patches?
    • .NET version upgrades?
    • Feature additions vs upstream compatibility?

Suggested approach

  • Add a docs/ directory or expand MEMORY.md with architecture notes
  • At minimum, document the fork maintenance strategy since upstream is dead — this is the highest-risk gap
## Finding (adversarial docs review 2026-03-17) The ersatztv project has good CLAUDE.md and MEMORY.md coverage for the tech stack and CI/CD, but **no design/architecture documentation** for the application-level concerns that matter most for maintaining this fork: ### What's missing 1. **Channel architecture**: How channels are defined, what content sources feed them, scheduling logic. The 29 (or 31?) channels are listed in `Docker/ErsatzTV.md` in server-management docs but the design decisions behind them aren't captured. 2. **M3U/XMLTV generation**: How playlists are built, the tvg-logo URL issue (Gitea issue #1), and how Jellyfin consumes the output. This is the core integration point. 3. **Logo fix design**: The logo watermark/fix script is documented in server-management's `Docker/ErsatzTV.md` but the reasoning and implementation approach aren't in this repo. 4. **Fork maintenance strategy**: Upstream is archived (Feb 2026). How do we handle: - Security patches? - .NET version upgrades? - Feature additions vs upstream compatibility? ### Suggested approach - Add a `docs/` directory or expand MEMORY.md with architecture notes - At minimum, document the fork maintenance strategy since upstream is dead — this is the highest-risk gap
timothy commented 2026-03-17 22:42:30 +01:00
Author
Owner
Copy Link

Addressed in f1e97b94. Added three docs:

docs/fork-strategy.md — Fork maintenance strategy covering:

  • Divergence policy (free divergence, no upstream to track)
  • .NET upgrade path (10 → 11, EF Core version coupling)
  • Dependency management (no central package management yet, manual audits, Dependabot not active on Gitea)
  • EF Core migration procedures (SQLite primary, MySQL secondary)
  • Docker base image tracking (FFmpeg image still pointing to upstream ghcr.io)
  • CVE response process
  • Key risks table (EF Core version gap, Lucene.Net beta, SkiaSharp native deps)

docs/channels.md — Channel architecture covering:

  • Channel entity fields and configuration options
  • Content source types (Collections, SmartCollections, Playlists, etc.)
  • Scheduling system (Classic/Block/Sequential/Scripted/ExternalJson)
  • Schedule item types (One, Multiple, Duration, Flood)
  • Playback orders and filler system
  • Playout pipeline diagram
  • Watermark system (including the hardcoded localhost note for issue #1)

docs/m3u-xmltv.md — M3U/XMLTV integration covering:

  • All IPTV endpoints
  • M3U generation flow (request-derived host, not hardcoded)
  • XMLTV generation (cached Scriban templates with placeholder substitution)
  • Jellyfin tuner setup
  • Issue #1 deep analysis: M3U/XMLTV paths are correct; the hardcoded localhost is only in ChannelLogoGenerator.GenerateChannelLogoUrl() used by watermarks, not M3U output. The logo issue may be a network/Host-header problem rather than a code bug.

Also updated CLAUDE.md with implementer workflow and project boundaries sections.

Addressed in f1e97b94. Added three docs: **`docs/fork-strategy.md`** — Fork maintenance strategy covering: - Divergence policy (free divergence, no upstream to track) - .NET upgrade path (10 → 11, EF Core version coupling) - Dependency management (no central package management yet, manual audits, Dependabot not active on Gitea) - EF Core migration procedures (SQLite primary, MySQL secondary) - Docker base image tracking (FFmpeg image still pointing to upstream ghcr.io) - CVE response process - Key risks table (EF Core version gap, Lucene.Net beta, SkiaSharp native deps) **`docs/channels.md`** — Channel architecture covering: - Channel entity fields and configuration options - Content source types (Collections, SmartCollections, Playlists, etc.) - Scheduling system (Classic/Block/Sequential/Scripted/ExternalJson) - Schedule item types (One, Multiple, Duration, Flood) - Playback orders and filler system - Playout pipeline diagram - Watermark system (including the hardcoded localhost note for issue #1) **`docs/m3u-xmltv.md`** — M3U/XMLTV integration covering: - All IPTV endpoints - M3U generation flow (request-derived host, not hardcoded) - XMLTV generation (cached Scriban templates with placeholder substitution) - Jellyfin tuner setup - Issue #1 deep analysis: M3U/XMLTV paths are correct; the hardcoded `localhost` is only in `ChannelLogoGenerator.GenerateChannelLogoUrl()` used by watermarks, not M3U output. The logo issue may be a network/Host-header problem rather than a code bug. Also updated CLAUDE.md with implementer workflow and project boundaries sections.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
api
REST API / HTTP endpoints
 bug
Something isn't working
 ci-cd
Build, test, deploy pipeline
 content
Channel content / schedules / playlists
 enhancement
New feature or improvement
 jellyfin
Jellyfin tuner / IPTV integration
 priority: high
priority: low
priority: medium
review
Adversarial review finding
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
timothy
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: timothy/ersatztv#6
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?