houndarr-architecture

name	houndarr-architecture
description	Houndarr's source layout and architectural patterns at file granularity. Loads when reading or editing src/houndarr/. Covers the per-file purpose for auth/, clients/, engine/, routes/, services/; the wire-models vs domain-models split; the *arr API spec snapshots under docs/api/; and pointers to the more specific database / engine skills for narrower scopes.
paths	["src/houndarr/**"]

Houndarr architecture reference

For narrower scopes:

• Database schema and migrations: see houndarr-database skill (loads on src/houndarr/database.py).
• Algorithmic verification: see verify-algorithms skill (loads on src/houndarr/engine/**).

Source layout

src/houndarr/
  __main__.py          # CLI entry point (Click), logging setup, uvicorn.run
  app.py               # create_app(), lifespan, middleware registration
  auth/                # AuthMiddleware, bcrypt, CSRF, rate limiter (seam package)
    password.py        # bcrypt verify / hash helpers
    rate_limit.py      # in-memory login rate limiter
    session.py         # signed session cookie encode / decode
    setup.py           # first-run admin setup + password policy
    csrf.py            # CSRF double-submit token rotation
    proxy_auth.py      # reverse-proxy trust gate and header extraction
    identity.py        # current-user resolution from session or proxy header
    middleware.py      # AuthMiddleware dispatch (builtin vs proxy path)
  config.py            # AppSettings dataclass, get_settings() singleton
  crypto.py            # Fernet encrypt/decrypt, master key management
  database.py          # get_db() context manager, schema migrations
  enums.py             # StrEnum consolidation (SearchKind, SearchAction, CycleTrigger, ItemType)
  errors.py            # HoundarrError hierarchy (Client/Engine/Service/Route)
  value_objects.py     # Frozen value objects shared across layers (ItemRef)
  clients/             # httpx-based *arr API clients
    base.py            # ArrClient ABC with _get()/_post() + raise_for_status() + get_queue_status()
    sonarr.py          # SonarrClient (episode/season search, v3 API)
    radarr.py          # RadarrClient (movie search, v3 API)
    lidarr.py          # LidarrClient (album/artist search, v1 API)
    readarr.py         # ReadarrClient (book/author search, v1 API)
    whisparr_v2.py     # WhisparrV2Client (Sonarr-based, episode/season search)
    whisparr_v3.py     # WhisparrV3Client (v3, Radarr-based, movie/scene search)
  engine/
    candidates.py      # SearchCandidate dataclass, ItemType re-export, date helpers
    search_loop.py     # run_instance_search(): unified search pipeline (missing/cutoff/upgrade passes, queue-backpressure gate)
    supervisor.py      # Supervisor: one asyncio.Task per enabled instance
    adapters/
      __init__.py      # AppAdapter dataclass, ADAPTERS registry, get_adapter()
      protocols.py     # AppAdapterProto: runtime_checkable Protocol matching the AppAdapter shape
      sonarr.py        # Sonarr adapter: candidate conversion + dispatch
      radarr.py        # Radarr adapter: candidate conversion + dispatch
      lidarr.py        # Lidarr adapter: candidate conversion + dispatch
      readarr.py       # Readarr adapter: candidate conversion + dispatch
      whisparr_v2.py   # Whisparr v2 adapter: candidate conversion + dispatch
      whisparr_v3.py   # Whisparr v3 adapter: movie/scene candidate conversion + dispatch
  routes/
    _htmx.py           # is_hx_request() shared helper for partial vs full renders
    pages.py           # Setup, Login, Dashboard, Logs, Settings page routes
    health.py          # GET /api/health (Docker HEALTHCHECK)
    settings/          # Settings surface split by concern
      __init__.py      # composes the sub-routers into a single settings_router
      _helpers.py      # template render, client build, connection check, validators
      page.py          # GET /settings
      account.py       # POST /settings/account/password
      instances.py     # /settings/instances/* (CRUD, test-connection, toggle)
    api/
      logs.py          # GET /api/logs (JSON, with cursor-based pagination)
      status.py        # GET /api/status (JSON, dashboard polling)
  services/
    instances.py       # Instance CRUD, InstanceType StrEnum
    cooldown.py        # Per-item search cooldown tracking
    url_validation.py  # SSRF guard for instance URLs

Wire models vs domain models

• Wire models (clients/_wire_models/): every *arr HTTP response is validated with a Pydantic model from this package before it reaches a parser. PaginatedResponse[T] (generic, PEP 695 syntax) covers the shared /wanted/* envelope; SystemStatus and QueueStatus back ArrClient.ping() and ArrClient.get_queue_status(); per-app *WantedEpisode / *WantedMovie / *WantedAlbum / *WantedBook and *LibraryEpisode / *LibraryMovie / *LibraryAlbum / *LibraryBook models name the record shapes. ArrSeries / ArrArtist / ArrAuthor type the parent-aggregate fetches. All wire models extend an internal _ArrModel that sets populate_by_name=True + extra="ignore" so unknown fields from new *arr versions never raise. Field names are snake_case in Python and alias to the camelCase the APIs serialise.
• Domain models (parsed result types): MissingEpisode, LibraryMovie, etc. are frozen dataclasses, one per client file next to the client that builds them. Every frozen dataclass uses slots=True. Instance composes seven frozen sub-structs (core, missing, cutoff, upgrade, schedule, snapshot, timestamps) and is itself frozen and slotted; callers evolve it through dataclasses.replace. AppSettings is the only deliberately-mutable dataclass (env overrides applied in-place on the lazy singleton).

Auth composition

Global AuthMiddleware (Starlette BaseHTTPMiddleware) routes every request through one of three path buckets; no per-route auth decorators:

• _API_KEY_PATHS (currently /api/v1/widget): the top-level dispatch() sends the request straight to _dispatch_api_key, which verifies X-Api-Key against the widget_api_key table (constant-time compare on the SHA-256 digest) and applies a per-IP attempt rate limit. Bypasses session and CSRF.
• _PUBLIC_PATHS (/setup, /login, /api/health, /static): no auth. Each of _dispatch_builtin and _dispatch_proxy short-circuits these before any session or proxy-header check.
• Everything else: mode-dependent. _dispatch_builtin enforces the session cookie + CSRF (default); _dispatch_proxy enforces the proxy-trust gate + CSRF when HOUNDARR_AUTH_MODE=proxy.

Proxy-auth trust and header reads flow through two primitives in auth.py: _is_trusted_proxy(request) (IP gate) and _extract_proxy_username(request) (header read, assumes trust already verified). The middleware's _dispatch_proxy and the standalone _validate_proxy_auth both compose these so the gate logic lives in one place.

Encryption

Master key in request.app.state.master_key; passed explicitly to service functions as master_key= kwarg; never imported globally.

HTMX

SPA-like shell navigation; nav links use hx-target="#app-content" with hx-swap="innerHTML" and hx-push-url="true". Routes check is_hx_request(request) from routes/_htmx.py and return either partial or full template. Templates are lazily initialised via a module-level singleton.

Supervisor

One asyncio.Task per enabled instance; 10s shutdown timeout.

search_log

Every search attempt writes a row with action searched / skipped / error / info.

*arr API reference (local)

Full upstream OpenAPI specs vendored under docs/api/ (one per app: sonarr, radarr, whisparr_v2, whisparr_v3, lidarr, readarr). Source of truth when touching clients/ code; see docs/api/README.md. Refreshed weekly (Mon 10:00 UTC) by api-snapshot-refresh.yml, so specs are never more than a week stale.