Questarr — Product Requirements Document
Version: 1.0Date: 2026-06-07
Author: Doezer Audience: Project owner, AI coding agents, open source contributors
Horizon: 6 months (Q3–Q4 2026)
1. Problem Statement
There is no automated, self-hosted tool to connect torrent/usenet indexers and download clients specifically for video games. Tools like Sonarr and Radarr solve this for TV and movies; Questarr fills the same gap for games. Without Questarr, a user who wants to automatically download a newly released game must manually search indexers, copy magnet/NZB links, and paste them into a download client — repeatedly, for every game, every update. Questarr eliminates that loop.2. Vision
Questarr is the *Arr-ecosystem equivalent for video games. It gives self-hosters a single, browser-based dashboard to discover, track, download, and organize their game library — automatically. The long-term vision is to be the connective tissue of the self-hosted gaming stack: integrated with indexers, download clients, external libraries (Steam, GOG), media management tools (Playnite, RomM, Gameyfin), and release trackers (xREL), while staying lightweight enough to run on a NAS or home server.3. Users & Personas
Primary — The Automated Downloader
A self-hoster who wants a set-it-and-forget-it pipeline. They add a game to their wishlist; Questarr searches indexers on a schedule, picks the best release, sends it to qBittorrent/SABnzbd/etc., monitors completion, and moves files to the right folder. They should rarely need to intervene. Core job: Don’t make me think about the download pipeline.Secondary — The Library Centralizer
A collector who already owns games on Steam, GOG, or a local filesystem and wants a single place to track everything. They use Questarr as a unified library view and may use it to fill gaps (games not on storefronts) via download. Core job: Show me everything I own in one place, regardless of source.Tertiary — The Retro Gamer
A user who wants to automate ROM downloads for retro gaming, feeding tools like RomM or ES-DE that read from a local path. Core job: Keep my ROM library up to date without manual searching.4. What Exists Today
Questarr is a working, production-ready application. The features below are live in the current release.Library Management
- Add games manually, via IGDB search, or by importing from Steam wishlist
- Game detail modal: cover art, metadata, user rating (0.5–10), hidden flag
- Filter, sort, and search the library
- Per-game status tracking (wanted, downloading, downloaded, etc.)
- Platform detection (from release title, IGDB data, fallback to PC)
Discovery
- IGDB-powered game discovery and metadata enrichment
- Steam App ID resolution + PCGamingWiki integration
- NexusMods trending mods per game
Search & Indexers
- Torznab and Newznab indexer aggregation
- Manual search with per-release download triggers
- Release blacklisting
- Preferred release groups setting
Download Client Integration
- qBittorrent, Transmission, rTorrent, SABnzbd, NZBGet
- Download status tracking and progress via WebSocket
- Auto-delete completed downloads setting
Automation
- Scheduled auto-search for wanted games
- Download completion checks (cron)
- xREL release monitoring with direct “add to library” from release list
- RSS feed monitoring
Calendar
- Release calendar for tracked games
Stats
- Library and download statistics dashboard
Settings & Config
- Per-user settings (preferred release groups, Steam sync)
- Indexer and downloader configuration UI
- System logs page
Infrastructure
- JWT authentication (single-user)
- SQLite database (Drizzle ORM)
- Docker-first deployment
- Socket.io real-time updates
- SSRF-protected outbound fetch
- React 18 SPA + Express REST API + TypeScript strict mode throughout
5. Six-Month Roadmap
Features are ordered by current priority. Each section includes the user value and the scope.P0 — Post-Processing Pipeline (in progress)
Problem: After a download completes, files land wherever the download client puts them. Users currently manage file organization manually or with external scripts. Feature: A configurable pipeline that runs after a download is marked complete:- Copy or move files to a user-defined destination path
- Support variable tokens in paths (e.g.
{game.title},{platform}) - Extract archives (
.rar,.zip, nested subdirs) - Optional: run a custom post-processing script (hook)
- Show post-processing status per download
P1 — Smart Game Backlog (Version-Aware Updates)
Problem: Once a game is downloaded, Questarr forgets about it. Users have no way to know when a newer version (patch, repack, upgrade) becomes available on indexers. Feature:- Track the last downloaded version per game (parsed from release title)
- On each scheduled search, compare new results against the stored version
- Notify the user only when a strictly higher version is found (e.g. v1.0 → v1.1)
- Option to auto-download upgrades
P2 — Direct Download Support (Real-Debrid and similar)
Problem: Some users prefer direct download services (Real-Debrid, AllDebrid, etc.) over traditional torrent/usenet pipelines — no seeding required. Feature:- New downloader type: “direct download / debrid service”
- Resolve magnet links or torrent files through the debrid API into direct HTTP links
- Trigger download to a local downloader or direct to server path
- Surface in the existing downloader configuration UI
P3 — External Library Sync
Problem: Users own games on Steam, GOG, and other platforms. Questarr currently only imports from Steam wishlists, not the actual library. Feature:- Import owned games from Steam library (via Steam API)
- Import from GOG (if API available, otherwise file-based)
- Filesystem scanner: detect games installed on a local path and add them to the library as “owned”
- Mark synced games with their source; avoid duplicates across sources
- Periodic background re-sync
P4 — Integrations with External Tools
Problem: Self-hosters already use tools like Playnite, Gameyfin, and RomM. Questarr should fit into those ecosystems rather than compete with them. Integrations:- Playnite ✅ Shipped — a Playnite extension (
extensions/playnite-questarr/) syncs the local library up to Questarr (matched by Steam App ID, then normalized title), can promote installed games fromwantedtoowned, and can request a game from Playnite’s right-click menu, which adds it aswantedand hands it to the existing auto-search pipeline. Backed by a dedicated integration API (/api/integration, seedocs/API.md) authenticated with a long-lived API key minted in Settings → Integrations, kept separate from the interactive JWT session so a leaked key cannot manage other keys or reach the rest of the app. - RomM (planned): Tag ROMs with metadata from Questarr; trigger ROM downloads via Questarr pipeline
- Gameyfin (planned): Notify or sync when a new game is added/downloaded
- Generic webhook (planned): POST to a user-defined URL on events (game added, download complete, post-processing done) — enables any integration not explicitly supported
P5 — Indexer Page Links
Problem: When a user wants more context about a specific release (description, NFO, comments), they have to manually navigate to the indexer. Feature:- Store and display a direct link to the release page on the indexer
- Surface as a “View on indexer” button in the download/search result UI
P6 — PostgreSQL Support (Re-introduction)
Problem: SQLite is limiting for users running Questarr in containerized or NAS environments where a shared DB or larger datasets are needed. PostgreSQL was previously supported and removed. Feature:- Re-introduce PostgreSQL as an optional database backend
- Maintain SQLite as the default (zero-config)
- Abstract the Drizzle schema to work cleanly on both dialects
- Document migration path from SQLite to PostgreSQL
Ongoing — Quality of Life, Design & UX
Not features but a standing priority for all 6 months. In line with the project philosophy: a well-maintained side project that is useful and pleasant to use beats a bloated one.- Mobile responsiveness: thumb-first navigation, touch-safe density, progressive disclosure on small screens
- Notification system improvements (granular per-event control)
- Search UX improvements (better result ranking, release group filtering)
- Performance: reduce unnecessary re-renders, paginate heavy lists
- Accessibility: aria-labels on all interactive elements, semantic HTML throughout
- Visual polish: consistent spacing, cover art quality, status color clarity
6. Non-Goals (Explicit Out-of-Scope)
The following will not be built within this roadmap and are not planned:7. Success Metrics
Growth
- Docker Hub pulls: 200k at project start → 500k by end of roadmap (6 months)
- GitHub stars: continued growth; no hard target, trend matters more than absolute number
- GitHub issues / discussions: response to every issue or question (community health)
Quality
- Zero regressions on post-processing pipeline at launch
- Test coverage maintained or improved (no coverage cliff from new features)
- No open P0/P1 bugs older than 30 days
Community
- Pre-release testing by users for major features (post-processing, smart backlog)
- Active engagement on Reddit posts and GitHub issues
- Feature requests acknowledged within 48 hours
8. Technical Constraints & Principles
- Docker-first: All features must work in a standard Docker container without host-level dependencies (except mapped volumes).
- SQLite by default: New features must not require PostgreSQL to function. Postgres is additive.
- Single-user: No multi-tenant data isolation required. JWT auth is sufficient for current scope.
- TypeScript strict: No
any, no untyped escape hatches introduced by new features. - SSRF protection: All outbound HTTP calls (new integrations, debrid APIs) must go through
ssrf.tsvalidation. - Backward compatibility: Settings, config, and the database schema must migrate cleanly. No silent breaking changes.
- Side-project pace: Features are shipped when they’re ready. No artificial deadlines.