silo-server/docs/superpowers/specs/2026-06-01-request-multi-instance-arr-routing-design.md

# Multi-Instance Sonarr/Radarr Routing for Requests (Seerr-style)

**Status:** Design approved, ready for implementation plan
**Date:** 2026-06-01
**Area:** `internal/requests`, `migrations/`, `web/src` (admin settings + request queue)

## Summary

Silo's request system today fulfills every approved request through a single
Radarr (movies) or single Sonarr (series) instance, at whatever quality that
one instance's profile is configured for. There is no 4K concept, no anime
handling, and exactly one instance per kind (`request_integrations.kind` is the
primary key).

This work replicates Seerr's Sonarr/Radarr management model *inside* Silo's own
request system (no external Seerr dependency):

- **Many instances per kind** — N Radarr and N Sonarr servers, each with its own
  connection, root folder, quality profile, and tags.
- **Default HD + Default 4K routing** — one HD-default and one 4K-default
  instance per kind; requests route to the matching default(s).
- **Per-server anime overrides** (Overseerr-style) — each instance carries an
  optional anime profile / root folder / tags applied when a title is detected
  as anime.
- **Entitlement-driven dual-quality fan-out** — a single user request can be
  fulfilled in **both** 1080p and 2160p when the requester's `MaxPlaybackQuality`
  allows 4K, or when an admin global toggle forces it for everyone.

The end-user request action is unchanged: quality is derived from the user's
existing entitlement, not a per-request choice.

## Goals

- Support multiple Radarr/Sonarr instances per kind.
- Route by quality (HD vs 4K) to per-kind default instances.
- Fan a single request out to both 1080p and 2160p targets based on the
  requester's `MaxPlaybackQuality` entitlement, with an admin override that
  forces dual-quality regardless of role.
- Apply per-instance anime overrides using Seerr-exact anime detection.
- Keep the request lifecycle (quotas, approval, reconcile) coherent under
  one-to-many fulfillment.

## Non-Goals

- No integration *with* a Seerr instance (an earlier idea, dropped). Silo
  remains the system of record.
- No per-request manual server/profile picker (Overseerr's advanced UI). Routing
  is automatic from defaults + entitlement.
- No separate 1080p/4K *availability* tracking. The pre-request presence check
  stays binary ("is this title in the Silo library at all").
- No admin-configurable anime keyword list (the heuristic is isolated so one can
  be added later).
- No dedicated-anime-instance flag — anime is handled by per-instance overrides
  (decided during design).

## Background: current flow

When a user requests a movie today (`internal/requests/service.go`):

1. **Browse/discover** via TMDB; each result carries a `RequestState`.
2. `CreateRequest` validates: requests enabled, not already available
   (presence), not already actively requested (dedup by `tmdb_id`), computes the
   requester's `EffectivePolicy` (quota, blocked, auto-approve), enforces quota.
3. Auto-approve users with a configured integration → row created `approved`,
   else `pending` for the admin queue.
4. `submitApprovedRequest` → `integrationForMediaType(mediaType)` finds the
   single instance by kind → `radarr.Client.SubmitMovie` POSTs to Radarr using
   that instance's root folder / quality profile / tags → request goes `queued`.
5. `ReconcileRequests` polls the instance: `queued → downloading → completed`
   (or `failed`).

The single insertion point that changes is step 4's instance selection.

## Design

### 1. Data model

**`request_integrations` — reworked from one-row-per-kind to many instances:**

| column | purpose |
|---|---|
| `id` (text PK, via `idgen`) | replaces `kind` as PK |
| `kind` (text, `radarr`\|`sonarr`) | now a plain column, keeps its CHECK |
| `name` (text) | admin-facing label |
| `enabled` (bool) | |
| `base_url`, `api_key_ref` | connection; API key stays a Fernet secret ref, never plaintext |
| `root_folder`, `quality_profile_id`, `tags[]` | standard (non-anime) defaults |
| `is_4k` (bool) | marks this as a 4K server |
| `is_default` (bool) | the HD default for its kind |
| `is_default_4k` (bool) | the 4K default for its kind |
| `anime_enabled` (bool) | apply anime overrides on this instance |
| `anime_quality_profile_id`, `anime_root_folder`, `anime_tags[]` | anime overrides |
| `options` (jsonb) | kind-specific extras (Radarr min-availability, Sonarr season-folders/series-type) |
| `last_check_*`, `created_at`, `updated_at` | unchanged |

**Invariants** (partial unique indexes + service validation):

- At most one `is_default` per kind; at most one `is_default_4k` per kind.
- `is_default ⇒ NOT is_4k` and `is_default_4k ⇒ is_4k`. The HD default is an HD
  server; the 4K default is a 4K server. HD and 4K defaults are therefore always
  distinct instances.

**New `media_request_targets`:**

| column | purpose |
|---|---|
| `id` (bigint identity PK) | |
| `request_id` (text → `media_requests` ON DELETE CASCADE) | |
| `integration_id` (text → `request_integrations` ON DELETE SET NULL) | |
| `integration_kind` (text snapshot) | survives instance deletion for history |
| `quality` (text, `1080p`\|`2160p`) | reuses `internal/access` presets |
| `is_anime` (bool) | which profile set was applied |
| `external_id`, `external_status`, `status`, `last_error` | per-target Radarr/Sonarr lifecycle |
| `created_at`, `updated_at` | |
| UNIQUE `(request_id, quality)` | one target per quality per request |

**`media_requests` changes:** the per-fulfillment columns
(`integration_kind`, `external_id`, `external_status`) move out to
`media_request_targets`. Add `is_anime` (bool). The request's `status` becomes an
**aggregate** over its targets (see §3). `idx_media_requests_active_tmdb` stays —
dedup is still one active request per title regardless of quality, and a
dual-quality request counts as **one** row against the user's quota.

### 2. Routing engine

A pure function `routeTargets(req, entitlement, settings, instances) -> []plannedTarget`
replaces `integrationForMediaType` as the selection point in
`submitApprovedRequest`.

**Inputs:** the request (incl. detected `is_anime`), the requester's
`MaxPlaybackQuality`, the global `force_dual_quality` setting, the configured
instances for the kind.

**Algorithm:**

1. **Kind** = `movie → radarr`, `series → sonarr`.
2. **Desired qualities:**
   - `1080p` is always desired (baseline for everyone).
   - Add `2160p` if `access.QualityAllowed("2160p", user.MaxPlaybackQuality)`
     **OR** `force_dual_quality` is on (the toggle overrides role).
3. **Pick the default instance per desired quality:** `1080p → is_default`,
   `2160p → is_default_4k` (for that kind).
4. **Profile selection per chosen instance:** if `req.is_anime` **and** the
   instance has `anime_enabled` → use its anime profile / root folder / tags
   (and, for Sonarr, `seriesType: anime`); otherwise the standard set.
5. Emit one `plannedTarget{instance, quality, isAnime, profile, rootFolder, tags}`
   per resolved quality.

**Edge cases:**

- A desired quality with **no default instance assigned** is silently skipped
  (cannot route 4K without a 4K default — matches "when both are assigned").
- **Zero** resolved targets (e.g. no HD default configured): the request stays
  `approved` but unfulfilled, with `last_error` = "no Radarr/Sonarr instance
  configured for this quality" so it surfaces in the admin queue.
- No dedup needed: the `is_default`/`is_default_4k` invariants guarantee HD and
  4K defaults are distinct instances.

### 3. Fulfillment & reconcile lifecycle

The adapter interfaces (`SubmitMovie`/`SubmitSeries`,
`CheckMovieStatus`/`CheckSeriesStatus`) are **unchanged** — they already take
`(req, integration)`. We call them **once per target**, passing a *resolved*
`Integration` whose `RootFolder`/`QualityProfileID`/`Tags` are filled from the
standard or anime block. Radarr/Sonarr's notion of "4K" is just that instance's
quality profile + root folder, so adapters stay quality-agnostic. (The Sonarr
adapter additionally sets `seriesType: anime` for anime targets.)

**On approval (`submitApprovedRequest`):**

1. `routeTargets(...)` → planned targets.
2. For each: insert a `media_request_targets` row, then call the matching
   adapter with the resolved instance + decrypted key.
3. On success → target `queued` with its `external_id`/`external_status`; on
   error → target `failed` + `last_error`.
4. **Recompute the request aggregate** in the same transaction as the target
   writes.

**Reconcile loop (`ReconcileRequests`):** for each candidate request, iterate its
**non-terminal targets**, load each target's instance by `integration_id`, call
the status adapter, update the target, then recompute the aggregate. Targets
reconcile independently.

**Aggregate recompute (single source of truth):**

- all targets `completed` → request `completed` (+ `completed_at`)
- any target `downloading` → `downloading`; else any `queued` → `queued`
- all targets `failed` → `outcome = failed`; **some** failed while others active
  → request stays active, `last_error` set from the failed target(s)

**Retry** is target-aware: an admin retry re-submits only the `failed` targets
(re-routing if instance config changed), leaving healthy targets alone.

### 4. Anime detection (Seerr-exact)

Detection matches upstream Seerr exactly — a single TMDB keyword id, no genre or
language fallback:

- `server/api/themoviedb/constants.ts`: `ANIME_KEYWORD_ID = 210024`
- `server/entity/MediaRequest.ts`: anime ⇔ `keywords.results` contains that id.

Implementation:

- A named constant `animeKeywordID = 210024`.
- `detectAnime(detail) bool` → true iff the TMDB keyword **ids** contain
  `210024`. Matching by id (not the name string) avoids false positives from
  neighboring keywords like "based on anime".
- Detected once at `CreateRequest` time and stored on `media_requests.is_anime`,
  so routing, reconcile, and retries stay consistent.
- Applies to both movies and series; ignored if no instance for that kind has
  `anime_enabled`.

**Supporting TMDB-client change:** extend `tmdb.MediaDetail` to carry keyword
**ids** (add `append_to_response=keywords` to the detail fetch). `GetMediaDetail`
is already called in the request path, so no extra round-trip beyond the append.
(`OriginalLanguage` is not needed under the parity-only decision but may be
mapped opportunistically since it is already in the response.)

The heuristic is isolated in one function so an admin-configurable keyword list
can be added later without touching routing.

### 5. Admin UI

`web/src/pages/admin-settings/IntegrationsSettings.tsx` and the setup wizard
`web/src/pages/setup-wizard/steps/IntegrationsStep.tsx` move from a single
Radarr/Sonarr form to an **instance-list manager** per kind:

**Per kind — list of instance cards** (add / edit / delete):

- Connection: name, base URL, API key (write-only; shows "configured" once set,
  never echoes the secret), **Test connection** → `LoadIntegrationOptions`
  populates root-folder and quality-profile **dropdowns**.
- Standard block: root folder, quality profile, tags.
- Quality role: `is_4k` switch, **Default (HD)** toggle, **Default 4K** toggle.
  The form enforces invariants client-side (no Default-HD on a 4K server;
  selecting a new default clears the prior one visually); server is source of
  truth.
- Anime block (collapsible, `anime_enabled`): anime quality profile, anime root
  folder, anime tags — dropdowns from the same test-connection options.

**Request settings panel** gains the **"Always fulfill in both 1080p and 4K"**
toggle (`force_dual_quality`) with helper text: applies to all requests when both
a Default HD and Default 4K instance exist, regardless of user role.

**`web/src/pages/AdminRequests.tsx`** (queue): each request row expands to show
its **targets** — quality badge (1080p/2160p), instance name, per-target status,
and per-target **retry** on failed ones. The aggregate status stays the headline.

**Setup wizard** stays minimal: add one Radarr + one Sonarr, auto-marked Default
HD. Advanced multi-instance/4K/anime config lives in the full settings page.

### 6. API contract & multi-repo coordination

**End-user request flow is unchanged** — quality is derived from
`MaxPlaybackQuality`, so the request action and payload are identical (no 4K
toggle, no new permission).

**`Request` response model** gains `is_anime` and a `targets[]` array
(`quality`, `instance_name`, `status`, `external_status`, `last_error`); the
top-level `integration_kind`/`external_id`/`external_status` are removed in favor
of the aggregate `status` + `targets`.

- Per `CLAUDE.md`'s multi-repo rule: end-user `silo-android` / `silo-apple`
  clients show a single aggregate status, so they likely need **no change** —
  but this is flagged as explicit Apple/Android follow-up to verify the request
  model tolerates the removed fields and ignores/parses the new `targets`.

**Admin endpoints** change from "upsert by kind" to instance CRUD:

- `GET/POST/PUT/DELETE` request integrations **by `id`**; `LoadIntegrationOptions`
  (test-connection) stays, keyed by instance.
- Default-toggle handled server-side transactionally (a new HD/4K default clears
  the prior one for that kind).
- `request_settings` gains `force_dual_quality`.
- Admin-web-only; no mobile client surface.

### 7. Migration & backfill

Next migration number: **169** (`169_request_multi_instance.{up,down}.sql`).

**Up:**

1. `ALTER request_integrations`: add `id`, `name`, `is_4k`, `is_default`,
   `is_default_4k`, `anime_enabled`, `anime_quality_profile_id`,
   `anime_root_folder`, `anime_tags[]`. Backfill existing rows: `id = gen`,
   `name = initcap(kind)`, `is_default = enabled` (the lone existing instance
   becomes that kind's HD default), everything else default/false. Swap the PK
   from `kind` to `id`; keep `kind` as a plain column with its CHECK.
2. Partial unique indexes: one `is_default` per kind, one `is_default_4k` per
   kind.
3. `CREATE media_request_targets` (per §1).
4. Backfill targets: for any `media_requests` row with an `external_id`, insert a
   target `(quality='1080p', is_anime=false, integration_id = that kind's
   instance, integration_kind, external_id, external_status, status = request's
   current status)`. Rows never submitted get no target yet.
5. `ALTER media_requests`: add `is_anime bool DEFAULT false`; drop
   `integration_kind`, `external_id`, `external_status`.
6. `idx_media_requests_active_tmdb` stays unchanged.

**Down:** re-add the three columns to `media_requests` and copy back the **1080p**
target's external fields; drop `media_request_targets`; drop `is_anime`; collapse
`request_integrations` to `kind`-PK by keeping each kind's `is_default` instance
and discarding extras; drop the new columns/indexes.

**Caveat (explicit):** the down migration is **lossy** — rollback discards any
additional instances (beyond one default per kind) and any 4K/anime target
history. This is the unavoidable cost of collapsing a one-to-many back to
one-to-one and is acceptable for a down migration.

**Go-side data access** (implementation, not SQL): `Integration` struct +
`scanIntegration` gain the new fields; the `Store` interface gains target CRUD +
`ListInstances(kind)`; `scanRequest` drops the external fields; `UpsertIntegration`
becomes id-based CRUD with default-toggle handling in-transaction.

### 8. Testing

- **`routeTargets` — table-driven (core of the feature):** matrix of
  {1080p vs 2160p entitlement} × {`force_dual_quality` on/off} × {which defaults
  exist} × {anime vs not} → expected target set.
- **`detectAnime`:** keyword `210024` present/absent; no name-substring false
  positives.
- **Aggregate recompute:** all-complete, partial-failure (request stays active +
  `last_error`), all-failed (`outcome=failed`), mixed downloading/queued.
- **Repository:** target CRUD; single-default-per-kind invariant rejects a second
  default; migration backfill yields exactly one 1080p target per previously
  submitted request.
- **Adapter:** Sonarr `SubmitSeries` sets `seriesType=anime` only for anime
  targets on anime-enabled instances.
- **Service:** extend `service_test.go` fakes — a 4K-entitled user's single
  request fans out to two adapter submissions with the right resolved instances;
  target-scoped retry re-submits only the failed target.
- **Frontend:** instance-form default-invariant enforcement; queue renders
  per-target rows + retry.

## Risks & open considerations

- **Reconcile cost** scales with targets, not requests (≤2× today). Bounded and
  acceptable; the reconcile loop already batches.
- **Anime keyword imperfection** is inherited from Seerr by design (parity
  choice). Mitigated by isolating `detectAnime` for future tuning.
- **Client model drift**: removing top-level external fields from `Request` must
  be verified against `silo-android` / `silo-apple` deserialization before
  release (flagged in §6).

## References

- Seerr upstream: https://github.com/seerr-team/seerr
  (`server/api/themoviedb/constants.ts`, `server/entity/MediaRequest.ts`)
- Overseerr anime discussions: #2876 (Sonarr for anime only), #3777 (configurable
  series type)
- Existing code: `internal/requests/{service,repository,types,store}.go`,
  `internal/requests/{radarr,sonarr,arrclient}`, `internal/access/quality.go`,
  `migrations/139_media_requests.up.sql`