docs(arch): DR-011 — retract DR-010's reach-back clause; search becomes query-driven

[ChrisonSimtian]

Answers the question "is reach-back actually the right way, and how do MediathekArr and RundfunkArr solve it?" — by checking, rather than reasoning from first principles. The answer changed the design.

What the comparables do

MediathekArr keeps no catalog. It is a live search proxy: "pretending to be a usenet indexer, but actually just fetching and parsing search results from MediathekViewWeb". TVDB supplies metadata; the effort goes into an "advanced filter and matching system" to survive "the horrendous lack of consistency and metadata in ARD/ZDF Mediatheken".

RundfunkArr uses curated configuration: data/shows.json (tvdbId, german name, aliases, episodes) plus data/rulesets.json (Mediathek topic, duration filters, season/episode regex, matching strategy), extended by community pull requests. SQLite is cache and history only.

Neither reads Sonarr's monitored series via the Sonarr API.

Why not

The Newznab contract is pull-by-query. Sonarr already knows what it monitors and issues t=tvsearch&q=…&tvdbid=…&season=&ep= for exactly what it wants. An indexer isn't supposed to know the monitored list — that's the client's job.

And the reason the question arose for us is our own choice, not a property of being an *arr indexer: DR-010 de-emphasised MediathekView in favour of the direct ARD/ZDF APIs. MediathekViewWeb is effectively a complete dump, so MediathekArr gets breadth for free. Our ARD crawler must walk A-Z catalog → show page → episodes → item page, so it has to be told which shows to walk. RundfunkArr has the identical constraint and answers it with human curation.

The work-list problem is self-inflicted by the direct-API decision.

What DR-011 decides

1. Search is query-driven — resolve on demand, cache, so any show works without pre-registration.
2. The standing crawl list survives only as RSS-feed input, since RSS-Sync genuinely needs a recent-releases list.
3. Reach-back is demoted to an optional pre-warm. Nothing may depend on a configured *arr instance to function.
4. Matching is where the effort belongs — that's where both comparables concentrate.

Reach-back was also insufficient on its own: an interactive search for a show that's unmonitored, or monitored but not yet crawled, returns nothing. A query-driven path was needed regardless — which demotes reach-back by definition.

Consequences

• ✅ Indexing works with zero *arr configuration, which is how a Newznab indexer should behave.
• ✅ Merged RSS feed for monitored shows #12 unblocked — the RSS feed can serve the standing crawl list without waiting on Optionally pre-warm the crawl list from Sonarr/Radarr monitored series #6.
• ✅ Sonarr/Radarr instance config UI (Blazor) #4/Env var bootstrap for first instance #5 stop being prerequisites for core function (still worthwhile for pre-warming and First-time setup wizard: guided initial configuration (db, auth, downloads, geo egress, *arr) #54's setup flow).
• ⚠️ On-demand search puts broadcaster latency in Sonarr's request path. Caching and timeouts become mandatory, not polish.
• ⚠️ Politeness/rate-limiting toward ARD/ZDF becomes a real concern once searches hit them live.

Honest about the evidence

Recorded in the DR rather than glossed:

• MediathekArr's README does not explicitly state live-versus-cached. "Fetching and parsing search results" strongly implies live, but it's an inference.
• Neither project documents RSS feed support — which is precisely the half that still needs a standing crawl. Our RSS design can't be copied from either and has to be reasoned out.

Document handling

DR-010's clause is struck through in place, not deleted, with a blockquote explaining the retraction — the history is worth keeping readable. Its header and the DR index record it. CLAUDE.md stated the retracted claim as fact and is corrected.

Backlog changes

#6	Re-scoped from "the crawl work-list" to optional pre-warm; no longer blocks #12
#58	New — query-driven search, incl. negative caching, timeouts and outbound rate-limiting
#49	On hold. Its SharpCompress advisory was already fixed by a version bump in #53, and the filmliste turns out to be the only full-catalog source available — exactly what MediathekArr depends on. Deleting it would remove our fallback if per-show crawling proves too narrow.

Docs only — no code, no test changes.

🤖 Generated with Claude Code