silo-server/docs/superpowers/specs/request-system.md

Media Request System Spec

Goal

Build a Silo-native request system that lets authenticated users discover and search TMDB movies and series, request missing media, and have approved requests fulfilled through Radarr and Sonarr.

Silo owns request state, request limits, approval policy, visibility, and catalog availability detection. Radarr and Sonarr are external fulfillment adapters.

V1 Scope

• TMDB movie and series search.
• Direct TMDB-backed discovery sections for requestable media.
• One canonical request per media item.
• Radarr fulfillment for movies.
• Sonarr fulfillment for whole series.
• Manual approval and configurable auto approval.
• Global rolling request limits with per-user overrides.
• User-facing request status badges on search and discovery results.
• Admin queue for all requests.
• Background reconciliation with Radarr, Sonarr, and the Silo catalog.

Non-Goals For V1

• Season-specific or episode-specific requests.
• Multiple Radarr or Sonarr instance routing.
• User-selected quality tiers per request.
• Public/global request lists for non-admin users.
• Request comments or conversation threads.
• Client app updates outside the server web UI.
• Collection-backed request discovery.

Request Visibility

Requests are not treated as highly private, but Silo should avoid exposing a global request list to normal users.

• Non-admin users can list only their own submitted requests.
• Admin users can list all requests and see requester, profile, and audit details.
• Search and discovery results include lightweight request state for the item.
• Search and discovery results must not expose requester identity, notes, or user counts to non-admin users.

If an item has already been requested, other users cannot request it. The item should show the existing request status instead.

Example search/discovery item state:

{
  "request": {
    "status": "queued",
    "requestable": false
  }
}

Status Model

The primary request status tracks the normal fulfillment path:

• pending: submitted and waiting for approval.
• approved: approved in Silo, but not yet handed to Radarr or Sonarr.
• queued: accepted by Radarr or Sonarr and waiting/searching.
• downloading: Radarr or Sonarr reports active download/import activity.
• completed: Silo catalog contains the requested media after a scan and provider-ID match.

Exceptional outcomes are separate from the main status ladder:

• declined
• cancelled
• failed

V1 assumption: declined, cancelled, and failed requests no longer block a new request for the same item, but they still count against historical request limits.

Request Limits

Admins configure a global rolling quota:

• enabled
• max_requests
• window_days

Admins can define per-user override modes:

• inherit global
• custom max_requests and window_days
• unlimited
• blocked from requesting

Quota rules:

• A new request counts when a request row is created.
• Every created request counts regardless of final status or outcome.
• Pending, approved, queued, downloading, completed, declined, cancelled, and failed requests all count during the rolling window.
• Duplicate attempts for an already-requested item do not count because no new request is created.
• Limits are enforced per Silo user account, not per household profile.
• The active profile is still recorded for audit and display.

Auto Approval

Auto approval supports a global default plus per-user override:

• inherit global
• always manual
• auto approve
• blocked

Auto approval only applies when:

• Requests are enabled.
• The user is within quota.
• The item is not already available in Silo.
• The item does not already have an active request.
• The relevant Radarr or Sonarr integration is configured.

Discovery

Request discovery is separate from Silo collections. It should call TMDB directly and enrich the results with Silo availability and request state. It must not create, sync, or depend on library_collections.

V1 discovery sections:

• trending_movies: /trending/movie/week
• trending_series: /trending/tv/week
• popular_movies: /movie/popular
• popular_series: /tv/popular
• upcoming_movies: /movie/upcoming
• on_air_series: /tv/on_the_air

Discovery responses should include:

• media type
• TMDB ID
• title
• year or first air year
• overview
• poster/backdrop URLs or paths
• local availability
• lightweight request state

Example:

{
  "media_type": "movie",
  "tmdb_id": 550,
  "title": "Fight Club",
  "year": 1999,
  "poster_path": "/pB8BM7pdSp6B6Ih7QZ4DrQ3PmJK.jpg",
  "availability": "missing",
  "request": {
    "status": null,
    "requestable": true
  }
}

Discovery implementation notes:

• Add a dedicated request discovery service under the request system.
• It may extend or reuse the low-level TMDB HTTP client.
• It must not use collection templates, collection sync, or collection persistence.
• Cache raw TMDB section responses briefly, for example 15-60 minutes.
• Enrich request and availability state at request time so status remains current.

Search

Search should call TMDB directly for movie and TV results, then enrich each result with:

• local Silo availability
• existing request status
• requestability under current settings and quota

Search should not require the item to exist in the Silo catalog.

Fulfillment

Movies

1. User selects a TMDB movie search/discovery result.
2. Silo validates quota, availability, duplicate request state, and policy.
3. Silo creates a request.
4. If auto approved, or after manual admin approval, Silo looks up/adds the movie in Radarr.
5. Silo stores the Radarr movie ID and moves the request to queued.
6. Background reconciliation updates the request to downloading from Radarr activity/history.
7. Silo marks the request completed only after the Silo catalog sees the matching TMDB ID.

Series

1. User selects a TMDB TV search/discovery result.
2. Silo resolves the TVDB ID needed by Sonarr.
3. Silo validates quota, availability, duplicate request state, and policy.
4. Silo creates a request.
5. If auto approved, or after manual admin approval, Silo adds the whole series in Sonarr using the default add behavior.
6. Silo stores the Sonarr series ID and moves the request to queued.
7. Background reconciliation updates the request to downloading from Sonarr activity/history.
8. Silo marks the request completed only after the Silo catalog sees the matching TMDB or TVDB ID.

Radarr Integration

The Radarr adapter should use Radarr v3 API endpoints:

• GET /api/v3/system/status for connection checks.
• GET /api/v3/rootfolder for root folder choices.
• GET /api/v3/qualityprofile for quality profiles.
• GET /api/v3/tag for tag choices.
• GET /api/v3/movie?tmdbId={id} to detect existing Radarr items.
• GET /api/v3/movie/lookup/tmdb?tmdbId={id} to hydrate add payloads.
• POST /api/v3/movie to add approved movies.

Configured movie options:

• root folder
• quality profile
• tags
• minimum availability
• search on add

Sonarr Integration

The Sonarr adapter should use Sonarr v3 API endpoints:

• GET /api/v3/system/status for connection checks.
• GET /api/v3/rootfolder for root folder choices.
• GET /api/v3/qualityprofile for quality profiles.
• GET /api/v3/tag for tag choices.
• GET /api/v3/series?tvdbId={id} to detect existing Sonarr items.
• GET /api/v3/series/lookup?term={term} to hydrate add payloads.
• POST /api/v3/series to add approved series.

Configured series options:

• root folder
• quality profile
• tags
• series type
• season folder
• search for missing episodes on add

API Surface

Profile-scoped routes:

• GET /api/v1/requests/search?q=&media_type=movie|series
• GET /api/v1/requests/discover
• GET /api/v1/requests/discover/{section}?page=1
• POST /api/v1/requests
• GET /api/v1/requests/mine
• GET /api/v1/requests/{id}

Admin routes:

• GET /api/v1/admin/requests
• POST /api/v1/admin/requests/{id}/approve
• POST /api/v1/admin/requests/{id}/decline
• POST /api/v1/admin/requests/{id}/retry
• GET /api/v1/admin/request-settings
• PUT /api/v1/admin/request-settings
• GET /api/v1/admin/request-users/{user_id}/limit
• PUT /api/v1/admin/request-users/{user_id}/limit
• GET /api/v1/admin/request-integrations
• PUT /api/v1/admin/request-integrations

Data Model

media_requests

Canonical media request records.

Suggested fields:

• id
• media_type
• provider
• tmdb_id
• tvdb_id
• imdb_id
• title
• year
• poster_path
• overview
• status
• outcome
• requested_by_user_id
• requested_by_profile_id
• integration_kind
• external_id
• external_status
• last_error
• created_at
• updated_at
• approved_at
• completed_at

Add a uniqueness constraint for active requests by (media_type, provider, tmdb_id). Declined, cancelled, failed, and completed requests should not block a future request.

media_request_events

Audit trail for request lifecycle changes.

Suggested fields:

• id
• request_id
• event_type
• actor_user_id
• actor_profile_id
• message
• metadata
• created_at

request_user_limits

Per-user quota and approval overrides.

Suggested fields:

• user_id
• limit_mode
• max_requests
• window_days
• approval_mode
• updated_at

request_settings

Global request settings.

Suggested fields:

• requests_enabled
• global_max_requests
• global_window_days
• global_auto_approval_enabled
• updated_at

request_integrations

Radarr and Sonarr configuration. API keys should use the existing sensitive settings pattern rather than being returned from API responses. The expected sensitive setting references are requests.radarr.api_key and requests.sonarr.api_key.

Suggested fields:

• kind
• enabled
• base_url
• api_key_ref
• root_folder
• quality_profile_id
• tags
• options
• last_check_at
• last_check_status
• last_check_error
• updated_at

UI Requirements

User UI:

• Request discovery page with TMDB sections.
• Search page or search mode that includes TMDB results.
• Clear badges for available, requested, and requestable states.
• Own requests page.
• Request button disabled when unavailable due to existing request, local availability, quota, or disabled system settings.

Admin UI:

• Request queue with filters by status and outcome.
• Approve, decline, and retry actions.
• Request settings page.
• Radarr and Sonarr configuration with connection checks.
• Per-user limit and approval override controls.

Acceptance Criteria

• A user can discover trending/popular/upcoming TMDB movies and series without touching Silo collections.
• A user can search TMDB and request a missing movie or whole series.
• Search and discovery items show whether they are available, already requested, or requestable.
• A user cannot request an item that already has an active request.
• Request limits count every created request within the rolling window, regardless of final status.
• Admins can configure global limits and per-user overrides.
• Admins can configure Radarr and Sonarr, approve/decline/retry requests, and see request audit history.
• Auto-approved requests are submitted to Radarr/Sonarr without admin action.
• Requests progress through pending, approved, queued, downloading, and completed.
• completed means Silo has scanned and matched the media in its catalog, not merely that Radarr or Sonarr reports completion.