Imported from zxibizz/releasarr (AGENTS.md). Install upstream with npx skills add zxibizz/releasarr. Copyright stays with the author.

AGENTS.md

Orientation for coding agents working in this repository. Read this first, then the deeper guide for whichever half you are touching.

What this project is

Releasarr orchestrates media requests across Sonarr, Radarr, Prowlarr, and qBittorrent: it tracks what the *arrs report as missing, searches indexers, downloads torrents, lets a human map files to episodes, and imports the result back through Sonarr and Radarr's manual import. See README.md for the user-facing picture.

Two halves, one contract:

Deeper guides

Read the relevant one before making non-trivial changes. They contain the concrete patterns, with file paths and snippets.

Narrower docs live next to the code they describe:

Hard rules

Violating these produces changes that look fine and break something elsewhere.

1. openapi.yaml changes first. It is consumed by three things: the backend's contract test, the frontend's type codegen, and the mock server. An API change means updating all four — spec, backend schemas, npm run codegen, and mock-server/.
2. Never hand-edit services/frontend/src/lib/api/generated/types.ts. It is committed but generated. Run npm run codegen from services/frontend/.
3. Dependencies point inward in the backend. application/ must not import FastAPI, SQLAlchemy models, or anything from infrastructure/. Use cases depend on Protocols in application/interfaces/; infrastructure/ implements them.
4. Route handlers stay thin. Map schema to command, await use_case.execute(...), map DTO to schema. Do not catch domain exceptions in routes — register them in DOMAIN_ERROR_MAP in services/backend/src/api/errors.py and let the global handler map them.
5. Never start background work inside the FastAPI app. The scheduler is a separate process. The API only writes rows to sync_jobs; the worker claims them.
6. All frontend HTTP goes through apiRequest in services/frontend/src/lib/api/client.ts. No bare fetch, no second client.
7. Add UI strings to both en and ru in services/frontend/src/locales/resources.ts. Russian plurals need _one/_few/_many/_other, English only _one/_other.
8. Status colors live in exactly one place: services/frontend/src/utils/status.ts, rendered by StatusBadge. Do not hardcode a status color anywhere else.
9. Review autogenerated migrations before applying them. Postgres enum changes need hand-written SQL; batch_alter_table silently no-ops there. See docs/data-model.md.
10. Every new backend route declares a guard. Depends(require_user), require_admin, or require_permission(Permission.X) from src/api/dependencies/auth.py — never add a router with no dependency and assume it inherits one. A use case that returns a single media_requests row must be checked against the caller's RequestScope before the row is returned; an out-of-scope row is a 404, not a 403. See docs/architecture.md.
11. Never cache /api in the service worker. There is no runtimeCaching block today, and adding one looks harmless and is not: every response is authenticated and the refresh cookie at /api/auth rotates exactly once per use, so a replayed response reaches the backend as a rotated token — which is what token theft looks like. navigateFallbackDenylist keeps /api out of the SPA fallback for the same reason. See services/frontend/docs/pwa.md.
12. Route loaders prefetch through prefetchWhenOnline. React Query pauses a query instead of failing it while the browser is offline, so a loader awaiting one never settles and the router then never renders the app. Any new ensureQueryData in services/frontend/src/router.tsx goes inside that wrapper.

Commands

Backend, from services/backend/:

uv sync                          # install
uv run fastapi dev src/api/app.py    # API on :8001
uv run python -m src.tasks.scheduler_service   # the worker, separately
uv run pytest                    # tests
uv run ruff check ./src          # lint (what CI runs)
uv run ruff format ./src         # format
uv run mypy src                  # type check
uv run alembic upgrade head      # apply migrations
uv run alembic revision --autogenerate -m "describe change"

Frontend, from services/frontend/:

npm install
npm run dev:mock                 # mock API on :8001 + Vite on :3000
npm test                         # vitest
npm run lint
npm run build                    # tsc --noEmit && vite build
npm run codegen                  # regenerate types from ../../openapi.yaml

The production image is Dockerfile.all-in-one, built from the repository root (docker build -f Dockerfile.all-in-one .) and served on :8050. For a containerised stack that reloads on edit instead, docker compose -f docker-compose.dev.yaml up --build — UI on :3000, API on :8000, scheduler in its own container.

Code style

Beyond the linters, this codebase has one strong convention worth matching.

Comments explain why, not what. The existing comments are prose that records a constraint, a tradeoff, or a decision someone would otherwise undo. They do not narrate the code. Match this; do not add comments that restate the next line, and do not leave behind comments that describe your edit.

# Sonarr and Radarr refuse an add without a quality profile, which releasarr
# itself never grabs by. Left unset, the first profile they report is used.
sonarr_quality_profile_id: int | None = Field(default=None)

Other conventions, in brief:

• Python: from __future__ import annotations at the top; @dataclass(slots=True) for commands, DTOs, and interface records; async throughout; __all__ at module end.
• Logging: get_logger(LogComponent.…) and structured kwargs (logger.info("Added series requests", tvdb_id=…, seasons=…)), never f-strings for identifiers.
• Partial updates: the UNSET sentinel from src/application/utility/sentinels.py distinguishes "not provided" from "explicitly null". None means null.
• TypeScript: @/ alias for src/; strict mode with noUnusedLocals; features own their api.ts and queries.ts; tests colocated as *.test.tsx, mobile variants as *.mobile.test.tsx.

Before you finish

• Ran the relevant tests and linters for the side you touched.
• If the API changed: openapi.yaml, backend schemas, npm run codegen, and the mock server are all in agreement, and uv run pytest tests/api/test_openapi_contract.py passes.
• If the schema changed: a migration exists and has been reviewed, not just autogenerated.
• If UI strings changed: both locales have the key.
• No new comments narrating what the code does.