An AI curator for a household media server. Pickarr suggests movies and series that fit the household's library and taste, explains why, and adds the chosen titles to Radarr or Sonarr with one click. It runs as a single container on a Synology NAS (LAN only, behind Nginx Proxy Manager) and is used from phones, desktops and the TV as a PWA.
Version 2 is a full rebuild. The binding specification is
docs/REBUILD-SPEC.md; the visual system ("Nachtvorstellung") is
docs/DESIGN-SYSTEM.md. Operations (deploy, rollout, rollback,
backups, troubleshooting) live in docs/OPERATIONS.md.
- Grounded recommendations (Entdecken): Claude ranks real TMDB candidates and explains its picks; hard rules (owned, seen, dismissed, exclusions, cooldown, profile rules) are enforced in code. Presets for moods, occasions and collections, "Mehr wie dieser", refine chips, auto count. Without AI credit or budget, a deterministic ranking takes over (Sparmodus).
- Household profiles: personas with rules (for example no horror, kids profile with FSK limit), per-profile seen state synced from Jellyfin, taste profiles with a feedback loop.
- Filmabend and Swipe & Match: one-tap picks for tonight from the own library, or a shared swipe deck for two.
- Library tools (Bibliothek): overview and stats, maintenance audit (quality, German audio, cutoff), collection gaps, seen list, history, watchlist CSV import, kids wishes with approval.
- Assistant: multi-turn chat with read-only tools on Radarr, Sonarr, Jellyfin and TMDB, plus a structured setup analysis.
- Scheduler and push: weekly digest, Jellyfin lists, rating pings and maintenance jobs run inside the app; push via ntfy, Discord, a webhook or plain text.
- Guardrail: nothing is ever added, downloaded, deleted or changed in Radarr/Sonarr without an explicit click; Pickarr's own adds can be undone within the undo window.
| Part | Stack | Path |
|---|---|---|
| Backend | Python 3.12, FastAPI, uvicorn (one process, one worker), SQLite (WAL, one writer thread), httpx, Anthropic SDK | backend/pickarr/ |
| Frontend | Svelte 5, Vite, TypeScript, PWA (service worker) | frontend/ |
| Shared | Media key test vectors used by both sides | shared/ |
| Container | Multi-stage Dockerfile (Node build, hash-checked Python deps, non-root runtime), compose.yaml |
repo root |
Data lives in DATA_DIR (/data in the container): the v2 database pickarr-v2.sqlite, daily
backups under backups/, and the untouched v1 files (pickarr.sqlite, seen_movies.json), which
are imported once, losslessly, at the first start.
All configuration comes from environment variables; secrets are never stored in the database or
shown in the UI. .env.example lists every variable with a dummy value and a
one-line comment (spec section 4.7). Required: RADARR_URL, RADARR_API_KEY, and with
AUTH_ENABLED=true (the default) APP_USER plus APP_PASSWORD_HASH. Without credentials and with
auth enabled the app starts in locked mode and refuses to serve (fail closed).
Create a password hash (the password is read interactively or from stdin, never from argv):
python -m pickarr.cli hash-passwordPut the value in single quotes in the .env file, because it contains $.
Requirements: Python 3.12 with uv, Node 24 or newer.
# backend
cd backend
uv venv .venv --python 3.12
uv pip sync requirements-dev.lock # hash-pinned lock (uses ./.venv)
.venv/bin/python -m pytest # Windows: .venv\Scripts\python.exe
# frontend
cd frontend
npm ci
npm run dev # Vite dev server, proxies /api to 127.0.0.1:8090
# run the app locally (serves the built frontend from frontend/dist)
cd frontend && npm run build
cd ../backend
DATA_DIR=/tmp/pickarr-data PICKARR_STATIC_DIR=../frontend/dist AUTH_ENABLED=false \
RADARR_URL=http://radarr.local:7878 RADARR_API_KEY=dummy .venv/bin/python -m pickarrscripts/check.sh runs every gate of spec 10.5: ruff, black, pytest with at least 80 % coverage,
npm ci, svelte-check (no warnings), vitest, vite build, the bundle budget, the API contract
check (gen:types + check:contract), export_openapi.py --check and the Docker build (skipped
with a SKIP line where Docker is not installed).
The HTTP contract is frozen in backend/pickarr/api/schemas.py and
frontend/src/lib/api/types.ts. After a deliberate contract change, regenerate the exported
schema and types:
python scripts/export_openapi.py # writes frontend/src/lib/api/openapi.json
cd frontend && npm run gen:types && npm run check:contractscripts/smoke.py (standard library only) checks a running instance end to end: health, app
shell and CSP, service worker and manifest, 401 without a session, CSRF and login, the main read
endpoints, the legacy /digest 410, logout. --ai additionally measures two real recommendation
runs (costs a few cents).
SMOKE_PASSWORD=... python scripts/smoke.py --base-url http://127.0.0.1:8090 --user maikbackend/ FastAPI app (pickarr/), tests (tests/platform, tests/domain, tests/ai)
frontend/ Svelte app (src/), static assets (public/), build scripts
shared/ media-key-vectors.json (shared test vectors)
scripts/ check.sh, export_openapi.py, smoke.py
docs/ REBUILD-SPEC.md, DESIGN-SYSTEM.md, OPERATIONS.md, contract-requests/, archive/
Dockerfile, compose.yaml, .env.example
Private household project. Streaming availability data is provided by JustWatch through TMDB; this product uses the TMDB API but is not endorsed or certified by TMDB.