# sofarr — Architecture

Comprehensive technical reference for the **sofarr** application: a personal media download dashboard that aggregates download activity from SABnzbd, Sonarr, Radarr, qBittorrent, Transmission, and rTorrent, filters results by Emby/Jellyfin user identity, and presents a real-time personalised dashboard.

---

## Table of Contents

1. [Introduction](#1-introduction)
2. [High-Level Architecture](#2-high-level-architecture)
3. [Pluggable Architecture Layers](#3-pluggable-architecture-layers)
4. [Webhook System](#4-webhook-system)
5. [Data Flow and Real-time Updates](#5-data-flow-and-real-time-updates)
6. [Caching and Smart Polling](#6-caching-and-smart-polling)
7. [Key Subsystems](#7-key-subsystems)
8. [Directory Structure](#8-directory-structure)
9. [Configuration and Environment Variables](#9-configuration-and-environment-variables)
10. [Security Model](#10-security-model)
11. [Technology Stack](#11-technology-stack)

---

## 1. Introduction

sofarr is a **Node.js/Express single-page application** that provides a personalised view of media downloads. It:

1. **Authenticates** users against an Emby/Jellyfin media server.
2. **Aggregates** download data from multiple *arr service instances and download clients.
3. **Filters** downloads per user — each user only sees media tagged with their username in Sonarr/Radarr.
4. **Presents** a real-time dashboard with progress, speeds, cover art, and status, updated either via background polling or instant webhook push from Sonarr/Radarr.

Admin users can view all users' downloads, see server status, cache statistics, poll timings, and perform blocklist-and-search operations.

Three pluggable layers form the architectural core:

| Layer | Name | Location |
|-------|------|----------|
| Download client abstraction | **PDCA** — Pluggable Download Client Architecture | `server/clients/` + `server/utils/downloadClients.js` |
| *arr data retrieval | **PALDRA** — Pluggable *Arr Library Data Retrieval Architecture | `server/utils/arrRetrievers.js` |
| Real-time push | **Webhook Receiver** | `server/routes/webhook.js` |

---

## 2. High-Level Architecture

```mermaid
flowchart TB
    subgraph Browser["Browser (SPA — public/)"]
        login["Login Form"]
        dash["Dashboard Cards"]
        status["Status Panel\n(Admin only)"]
        history["History Tab"]
    end

    subgraph Server["Express Server (:3001)"]
        direction TB
        mw["Middleware\nHelmet · rate-limit · cookie-parser · verifyCsrf"]
        auth_r["Auth Routes\n/api/auth"]
        dash_r["Dashboard Routes\n/api/dashboard  (SSE /stream)"]
        wh_r["Webhook Routes\n/api/webhook/sonarr|radarr"]
        hist_r["History Routes\n/api/history"]
        proxy_r["Proxy Routes\n/api/sonarr · /api/radarr\n/api/sabnzbd · /api/emby"]

        subgraph Core["Core Utilities"]
            poller["Poller\n(smart background polling)"]
            cache["MemoryCache\n(poll:* + webhook metrics)"]
            pdca["PDCA Registry\n(download clients)"]
            paldra["PALDRA Registry\n(arr retrievers)"]
            tokenstore["TokenStore\n(tokens.json)"]
        end
    end

    subgraph Ext["External Services"]
        sab["SABnzbd"]
        sonarr["Sonarr"]
        radarr["Radarr"]
        qbt["qBittorrent"]
        rtorrent["rTorrent"]
        transmission["Transmission"]
        emby["Emby / Jellyfin"]
    end

    login -->|"POST /api/auth/login"| auth_r
    dash  -->|"GET /api/dashboard/stream (SSE)"| dash_r
    status -->|"GET /api/dashboard/status"| dash_r
    history -->|"GET /api/history/recent"| hist_r

    auth_r --> tokenstore
    auth_r -->|"authenticate"| emby

    dash_r --> cache
    dash_r --> poller
    wh_r --> cache
    wh_r --> paldra
    hist_r --> cache
    proxy_r -->|"proxy"| sonarr & radarr & sab & emby

    poller --> pdca & paldra
    poller --> cache
    pdca -->|"HTTP/API"| sab & qbt & rtorrent & transmission
    paldra -->|"HTTP/API"| sonarr & radarr

    sonarr & radarr -->|"POST /api/webhook/*"| wh_r
```

### Request routing summary

```
Browser (SPA)
    │  POST /api/auth/login          → Auth routes → Emby verify → set httpOnly cookie
    │  GET  /api/dashboard/stream    → SSE stream → cache → matched downloads
    │  POST /api/webhook/*           ← Sonarr/Radarr push events
    │
    ▼
Express Server (:3001)
    ├── Helmet (CSP nonce, HSTS, X-Frame-Options, …)
    ├── express-rate-limit (300/15 min general; 60/1 min webhook; 10 fails/15 min login)
    ├── cookie-parser (HMAC-signed session cookie)
    ├── verifyCsrf (double-submit cookie, all state-changing /api routes except auth + webhook)
    │
    ├── /api/auth          → login, logout, me, csrf
    ├── /api/webhook       → [rate-limit] → [secret validation] → [payload validation]
    │                        → [replay check] → updateWebhookMetrics → processWebhookEvent
    ├── /api/dashboard     → requireAuth → read cache → match downloads → SSE/JSON
    ├── /api/history       → requireAuth → historyFetcher (5 min cache) → filter + dedup
    ├── /api/sonarr|radarr → requireAuth → verifyCsrf → proxy to *arr API
    └── /api/sabnzbd|emby  → requireAuth → verifyCsrf → proxy

Background:
    Poller (setInterval POLL_INTERVAL ms)
        └── shouldSkipInstancePolling? ──yes──► extend cache TTL, increment pollsSkipped
                │ no (or fallback triggered)
                ▼
            PDCA Registry.getDownloadsByClientType()
            PALDRA Registry.getQueuesByType() / getHistoryByType() / getTagsByType()
                │
                ▼
            cache.set('poll:*', data, TTL)
                │
                ▼
            notify pollSubscribers → SSE push to all connected browsers
```

---

## 3. Pluggable Architecture Layers

### 3.1 Pluggable Download Client Architecture (PDCA)

#### Overview

The PDCA provides a unified, extensible interface for all download clients. This abstraction layer enables:

- **Client-agnostic polling** — the poller contains no client-specific logic.
- **Easy extension** — add a new client by implementing one interface.
- **Consistent normalisation** — all clients return standardised download objects.
- **Centralised configuration** — a single registry manages all instances.
- **Error isolation** — individual client failures do not affect other clients.

#### Abstract Base Class

All download clients extend `DownloadClient` (`server/clients/DownloadClient.js`):

```javascript
class DownloadClient {
  constructor(instanceConfig)
  getClientType(): string
  getInstanceId(): string
  async testConnection(): Promise<boolean>
  async getActiveDownloads(): Promise<NormalizedDownload[]>
  async getClientStatus(): Promise<Object|null>   // optional
  normalizeDownload(download): NormalizedDownload
}
```

#### Client Implementations

```
DownloadClient (abstract)
├── SABnzbdClient       — REST API, API key auth; handles queue + history; normalises time/size units
├── QBittorrentClient   — Sync API (incremental deltas), cookie auth, fallback to /torrents/info
├── TransmissionClient  — JSON-RPC, session-ID management
└── RTorrentClient      — XML-RPC (xmlrpc 1.3.2), HTTP Basic Auth; maps rTorrent states to normalised statuses
```

#### Normalised Download Schema

Every client returns objects conforming to this schema:

```javascript
interface NormalizedDownload {
  id: string                    // Client-specific unique ID
  title: string                 // Download title/name
  type: 'usenet' | 'torrent'    // Download type
  client: string                // Client identifier ('sabnzbd', 'qbittorrent', etc.)
  instanceId: string            // Instance identifier
  instanceName: string          // Instance display name
  status: string                // Normalised status (Downloading, Seeding, etc.)
  progress: number              // Progress percentage (0–100)
  size: number                  // Total size in bytes
  downloaded: number            // Downloaded bytes
  speed: number                 // Current speed in bytes/sec
  eta: number | null            // ETA in seconds, null if unknown
  category?: string             // Download category (optional)
  tags?: string[]               // Download tags (optional)
  savePath?: string             // Save path (optional)
  addedOn?: string              // Added timestamp (optional)
  arrQueueId?: number           // Sonarr/Radarr queue ID (optional)
  arrType?: 'series' | 'movie'  // Sonarr/Radarr type (optional)
  raw?: any                     // Original client response (escape hatch)
}
```

#### Registry (`server/utils/downloadClients.js`)

`DownloadClientRegistry` manages all instances:

```javascript
class DownloadClientRegistry {
  async initialize()                                     // Create clients from config
  getAllClients(): DownloadClient[]
  getClient(instanceId): DownloadClient
  getClientsByType(type): DownloadClient[]
  async getAllDownloads(): NormalizedDownload[]           // Fetch from all clients in parallel
  async testAllConnections(): Promise<ConnectionTestResult[]>
  async getAllClientStatuses(): Promise<ClientStatus[]>
}
```

**Configuration-driven:** reads from `*_INSTANCES` environment variables (JSON array format) with fallback to legacy `*_URL` / `*_API_KEY` / `*_USERNAME` / `*_PASSWORD` variables.

#### qBittorrent Sync API Details

Each `QBittorrentClient` instance maintains:

- **`lastRid`** — response ID from the previous `sync/maindata` call (starts at `0`).
- **`torrentMap`** — `Map<hash, torrent>` holding the complete state for every known torrent.
- **`fallbackThisCycle`** — boolean tracking whether this poll cycle has already fallen back to the legacy endpoint.

Per-cycle flow:
1. Attempt `GET /api/v2/sync/maindata?rid={lastRid}`.
2. If `full_update` is `true`, rebuild `torrentMap` from scratch.
3. Otherwise merge delta fields into existing entries; remove `torrents_removed` hashes.
4. On Sync API failure, fall back **once per cycle** to `GET /api/v2/torrents/info`.
5. If the fallback also fails, return an empty array for this cycle and log the error.

The rest of the application (poller, dashboard) receives data in the same format regardless of which path was taken.

#### Adding a New Download Client

1. Create `server/clients/MyClient.js` extending `DownloadClient`.
2. Implement `getActiveDownloads()` returning `NormalizedDownload[]`.
3. Register the class in the registry factory inside `server/utils/downloadClients.js`.

---

### 3.2 Pluggable *arr Retrieval Layer (PALDRA)

#### Overview

`server/utils/arrRetrievers.js` exports `arrRetrieverRegistry`, a singleton that manages one `PollingSonarrRetriever` or `PollingRadarrRetriever` per configured instance. It provides a uniform interface for fetching queue, history, and tag data, keyed by service type.

The registry is used by both the background poller and the webhook processor, guaranteeing consistent data shapes across both update paths.

#### Registry API

```javascript
arrRetrieverRegistry = {
  async initialize()                              // idempotent; reads config once
  getAllRetrievers(): ArrRetriever[]
  getRetriever(instanceId): ArrRetriever | null
  getRetrieversByType(type): ArrRetriever[]       // 'sonarr' | 'radarr'

  // Typed fetch methods — all return { sonarr: [...], radarr: [...] }
  async getQueuesByType(): Promise<{ sonarr, radarr }>
  async getHistoryByType(options?): Promise<{ sonarr, radarr }>
  async getTagsByType(): Promise<{ sonarr, radarr }>
}
```

Each result element is `{ instance: instanceId, data: <arr API response> }`, allowing callers to look up instance credentials from `config.js`.

#### Retriever API Calls

| Task | Endpoint | Key Parameters |
|------|----------|----------------|
| Sonarr tags | `GET /api/v3/tag` | — |
| Sonarr queue | `GET /api/v3/queue` | `includeSeries=true`, `includeEpisode=true` |
| Sonarr history | `GET /api/v3/history` | `pageSize=10`, `includeEpisode=true` |
| Radarr tags | `GET /api/v3/tag` | — |
| Radarr queue | `GET /api/v3/queue` | `includeMovie=true` |
| Radarr history | `GET /api/v3/history` | `pageSize=10` |

All fetches across all instances run in parallel via `Promise.allSettled`, so a single failing instance does not block others.

---

## 4. Webhook System

### 4.1 Webhook Receiver

sofarr exposes two webhook endpoints that Sonarr and Radarr can be configured to call on every automation event:

```
POST /api/webhook/sonarr
POST /api/webhook/radarr
```

Both endpoints share identical processing logic:

```
Sonarr/Radarr
    POST /api/webhook/sonarr
    Headers: X-Sofarr-Webhook-Secret: <secret>
    Body:    { "eventType": "Grab", "instanceName": "Main Sonarr",
               "date": "2026-05-19T10:00:00.000Z", … }
        │
        ▼
    webhookLimiter (60 req/min/IP)
        │
        ▼
    validateWebhookSecret()  ──fail──► 401 Unauthorized
        │ ok
        ▼
    validatePayload()        ──fail──► 400 Bad Request
        │ ok
        ▼
    isReplay()               ──yes───► 200 { received: true, duplicate: true }
        │ no
        ▼
    cache.updateWebhookMetrics(instance.url)   ← activates smart polling skip
        │
        ▼
    200 { received: true }   ← response sent immediately
        │
        ▼  (fire-and-forget)
    processWebhookEvent(serviceType, eventType)
        ├── classify: QUEUE_EVENT or HISTORY_EVENT
        ├── arrRetrieverRegistry.getQueuesByType() / getHistoryByType()
        ├── cache.set('poll:sonarr-queue' | 'poll:sonarr-history', …, CACHE_TTL)
        └── pollAllServices() → pollSubscribers.forEach(cb) → SSE push
```

The 200 response is sent **before** the background cache refresh completes, ensuring Sonarr/Radarr never have to wait for sofarr's downstream API calls.

#### Event Classification

| Event type | Classification | Cache keys refreshed |
|------------|---------------|---------------------|
| `Grab`, `Download`, `DownloadFailed`, `ManualInteractionRequired` | `QUEUE_EVENT` | `poll:{type}-queue` |
| `DownloadFolderImported`, `ImportFailed`, `EpisodeFileRenamed`, `MovieFileRenamed`, `EpisodeFileRenamedBySeries` | `HISTORY_EVENT` | `poll:{type}-history` |
| `Test`, `Rename`, `SeriesAdd`, `SeriesDelete`, `MovieAdd`, `MovieDelete`, `MovieFileDelete`, `Health`, `ApplicationUpdate`, `HealthRestored` | Informational — no refresh | — |

#### Accepted Event Types

The full allowlist enforced by `validatePayload()`:

```
Test · Grab · Download · DownloadFailed · ManualInteractionRequired
DownloadFolderImported · ImportFailed
EpisodeFileRenamed · MovieFileRenamed · EpisodeFileRenamedBySeries
Rename · SeriesAdd · SeriesDelete · MovieAdd · MovieDelete · MovieFileDelete
Health · ApplicationUpdate · HealthRestored
```

Any `eventType` not in this set is rejected with `400 Bad Request`.

---

### 4.2 Real-time Cache and SSE Integration

When a webhook event is classified as a `QUEUE_EVENT` or `HISTORY_EVENT`:

1. `arrRetrieverRegistry` fetches fresh data from the relevant *arr instances (in parallel, via PALDRA).
2. The result is written directly into the shared `MemoryCache` under the same `poll:*` key the poller uses — ensuring both paths produce identical cache shapes.
3. `pollAllServices()` is called, which iterates `pollSubscribers` and pushes the updated payload to every open SSE connection immediately.

The dashboard therefore receives fresh data within the round-trip time of the *arr API call, without waiting for the next poll cycle.

---

### 4.3 Notification Management API

The `sonarr.js` and `radarr.js` route modules expose endpoints (under `/api/sonarr` and `/api/radarr` respectively, behind `requireAuth` + `verifyCsrf`) for one-click webhook configuration. These proxy to the *arr notification API to create, update, or remove the sofarr webhook connection in Sonarr/Radarr, using `SOFARR_BASE_URL` to construct the target URL.

---

## 5. Data Flow and Real-time Updates

### 5.1 Polling Cycle (background path)

Every `POLL_INTERVAL` ms the poller fetches all services in parallel:

| Task | API | Key parameters |
|------|-----|----------------|
| SABnzbd Queue | `GET /api?mode=queue` | `output=json` |
| SABnzbd History | `GET /api?mode=history` | `limit=10` |
| Sonarr Tags | `GET /api/v3/tag` | — |
| Sonarr Queue | `GET /api/v3/queue` | `includeSeries=true`, `includeEpisode=true` |
| Sonarr History | `GET /api/v3/history` | `pageSize=10`, `includeEpisode=true` |
| Radarr Tags | `GET /api/v3/tag` | — |
| Radarr Queue | `GET /api/v3/queue` | `includeMovie=true` |
| Radarr History | `GET /api/v3/history` | `pageSize=10` |
| qBittorrent | `GET /api/v2/sync/maindata?rid=N` | Fallback: `GET /api/v2/torrents/info` |

Results are stored in `MemoryCache` under `poll:*` keys with TTL `POLL_INTERVAL × 3`. Per-task timings are recorded in `lastPollTimings` for the admin status panel.

```mermaid
sequenceDiagram
    participant Entry as index.js
    participant Poller
    participant PDCA as PDCA Registry
    participant PALDRA as PALDRA Registry
    participant Cache as MemoryCache
    participant SSE as SSE Subscribers

    Entry->>Poller: startPoller()
    loop Every POLL_INTERVAL ms
        Poller->>Poller: polling flag check (skip if concurrent)
        Poller->>PDCA: getDownloadsByClientType()
        Poller->>PALDRA: getQueuesByType() / getHistoryByType() / getTagsByType()
        PDCA-->>Poller: { sabnzbd, qbittorrent, rtorrent, transmission }
        PALDRA-->>Poller: { sonarr: [...], radarr: [...] }
        Poller->>Cache: set poll:* keys (TTL = POLL_INTERVAL × 3)
        Poller->>SSE: notify all subscribers → push data: frame
    end
```

### 5.2 Webhook Path (real-time update)

```mermaid
sequenceDiagram
    participant Arr as Sonarr/Radarr
    participant WH as /api/webhook/sonarr
    participant Cache as MemoryCache
    participant PALDRA as PALDRA Registry
    participant SSE as SSE Subscribers

    Arr->>WH: POST /api/webhook/sonarr { eventType, instanceName, date }
    WH->>WH: validateSecret + validatePayload + isReplay
    WH->>Cache: updateWebhookMetrics(instance.url)
    WH-->>Arr: 200 { received: true }
    Note over WH: fire-and-forget begins
    WH->>PALDRA: getQueuesByType() or getHistoryByType()
    PALDRA-->>WH: fresh arr data
    WH->>Cache: set poll:sonarr-queue / poll:sonarr-history
    WH->>SSE: pollAllServices() → push data: frame to all clients
```

### 5.3 SSE Stream

When a browser opens `GET /api/dashboard/stream`:

1. Server sets `Content-Type: text/event-stream`, disables buffering (`X-Accel-Buffering: no`).
2. Immediately builds and sends the first payload (same matching logic as `/user-downloads`).
3. Registers a callback with the poller's `onPollComplete` subscriber set.
4. After every subsequent poll cycle (or webhook-triggered broadcast), the callback fires, rebuilds the payload, and writes a `data:` SSE frame.
5. A 25-second heartbeat comment (`: heartbeat`) keeps the connection alive through proxies.
6. On client disconnect: deregisters callback, stops heartbeat, removes from `activeClients` map.

The browser's native `EventSource` API handles reconnection automatically on network interruption.

**SSE Payload Structure**

```javascript
{
  user: string,              // Username
  isAdmin: boolean,          // Admin flag
  downloads: DownloadObject[],  // Matched download objects (see Section 5.4)
  downloadClients: {         // Configured download clients for ordering/filtering
    id: string,              // Instance identifier
    name: string,            // Instance display name
    type: string             // Client type ('sabnzbd', 'qbittorrent', 'transmission', 'rtorrent')
  }[]
}
```

### 5.4 Download Matching Pipeline

For each connected user the server:

1. Reads all `poll:*` keys from `MemoryCache`.
2. Builds `seriesMap`, `moviesMap`, `sonarrTagMap`, and `radarrTagMap` from embedded objects in queue records.
3. For each SABnzbd/qBittorrent download item, attempts matches in priority order: Sonarr queue → Radarr queue → Sonarr history → Radarr history.
4. Title matching is a **bidirectional, case-insensitive substring match**: `rTitle.includes(dlTitle) || dlTitle.includes(rTitle)`.
5. For each match, resolves the series/movie, extracts user tags, checks ownership.
6. Returns only the requesting user's downloads (or all, if admin with `showAll=true`).

```mermaid
flowchart TD
    Start(["Download item"]) --> SQ{"Sonarr QUEUE\nmatch (title)"}
    SQ -->|yes| SQR["Resolve series · extract user tag"]
    SQ -->|no| RQ{"Radarr QUEUE\nmatch (title)"}
    RQ -->|yes| RQR["Resolve movie · extract user tag"]
    RQ -->|no| SH{"Sonarr HISTORY\nmatch (title)"}
    SH -->|yes| SHR["Resolve series via seriesId"]
    SH -->|no| RH{"Radarr HISTORY\nmatch (title)"}
    RH -->|yes| RHR["Resolve movie via movieId"]
    RH -->|no| Skip(["Skip — unmatched"])

    SQR & RQR & SHR & RHR --> Tagged{"Tag matches\nrequesting user?"}
    Tagged -->|yes| Include(["Include in response"])
    Tagged -->|no| Skip
```

#### Tag matching

Users are matched to downloads via Sonarr/Radarr tags:

1. **Exact match** — tag label (lowercased) === username (lowercased).
2. **Sanitised match** — handles Ombi tag mangling: `sanitizeTagLabel()` converts to lowercase, replaces non-alphanumeric chars with hyphens, collapses runs, trims.

#### Client ordering and filtering

Matched download objects include `client`, `instanceId`, and `instanceName` fields. The frontend:
1. Receives a `downloadClients` array from the SSE payload with all configured clients in configuration order
2. Displays a multi-select filter allowing users to choose which clients to view
3. Sorts downloads by client order (downloads from the first configured client appear first)
4. Filters downloads to show only those from selected client instances

#### Matched download object fields

| Field | Type | Description |
|-------|------|-------------|
| `type` | `'series'`/`'movie'`/`'torrent'` | Media type |
| `title` | string | Raw download title |
| `coverArt` | string/null | Poster URL from *arr |
| `status` | string | Download status |
| `progress` | string | Percentage complete |
| `size`/`mb`/`mbmissing` | string/number | Size info |
| `speed` | string | Current download speed |
| `eta` | string | Estimated time remaining |
| `seriesName`/`movieName` | string | Friendly media title |
| `episodes` | `{season, episode, title}[]` | Episodes covered (sorted); empty array if Sonarr has no data |
| `allTags` | string[] | All resolved tag labels on the series/movie |
| `matchedUserTag` | string/null | Tag label matching the requesting user |
| `tagBadges` | `{label, matchedUser}[]`/undefined | (Admin `showAll` only) each tag classified against Emby user list |
| `importIssues` | string[]/null | Import warning/error messages |
| `canBlocklist` | boolean | `true` if the current user may blocklist this download |
| `downloadPath` | string/null | (Admin) Download client path |
| `targetPath` | string/null | (Admin) *arr target path |
| `arrLink` | string/null | (Admin) Link to *arr web UI |
| `arrQueueId` | number/null | (Admin) Sonarr/Radarr queue record id |
| `arrType` | `'sonarr'`/`'radarr'`/null | (Admin) Which *arr service owns this queue entry |
| `arrInstanceUrl` | string/null | (Admin) Base URL of the *arr instance |
| `arrInstanceKey` | string/null | (Admin) API key for the *arr instance |
| `arrContentId` | number/null | (Admin) `episodeId` or `movieId` for triggering a new search |
| `arrContentType` | `'episode'`/`'movie'`/null | (Admin) Content type for search command |
| `client` | string | Download client type ('sabnzbd', 'qbittorrent', 'transmission', 'rtorrent') |
| `instanceId` | string | Instance identifier matching the configured client ID |
| `instanceName` | string | Instance display name from configuration |
| `addedOn` | number/null | (qBittorrent) Unix timestamp when torrent was added |
| `availableForUpgrade` | boolean/undefined | (History) `true` when outcome is `failed` but content is on disk |

---

## 6. Caching and Smart Polling

### 6.1 Cache Layer

`server/utils/cache.js` exports a singleton `MemoryCache` backed by a `Map`. Each entry carries an expiration timestamp. The cache is shared by the poller, webhook processor, and all route modules.

```javascript
class MemoryCache {
  get(key): any
  set(key, value, ttlMs)
  invalidate(key)
  clear()
  getStats(): CacheStats          // per-key size, item count, TTL remaining

  // Webhook metrics helpers
  updateWebhookMetrics(instanceUrl)
  getWebhookMetrics(instanceUrl): { eventsReceived, lastWebhookTimestamp, pollsSkipped }
  getGlobalWebhookMetrics(): { lastGlobalWebhookTimestamp }
}
```

### 6.2 Cache Keys

| Key | Content | TTL |
|-----|---------|-----|
| `poll:sab-queue` | `{ slots, status, speed, kbpersec }` | `POLL_INTERVAL × 3` |
| `poll:sab-history` | `{ slots }` | `POLL_INTERVAL × 3` |
| `poll:sonarr-queue` | `{ records }` with embedded `series` objects + `_instanceUrl`/`_instanceKey` | `POLL_INTERVAL × 3` |
| `poll:sonarr-history` | `{ records }` — lightweight, no embedded objects | `POLL_INTERVAL × 3` |
| `poll:sonarr-tags` | `[{ instance, data: [{id, label}] }]` | `POLL_INTERVAL × 3` |
| `poll:radarr-queue` | `{ records }` with embedded `movie` objects + `_instanceUrl`/`_instanceKey` | `POLL_INTERVAL × 3` |
| `poll:radarr-history` | `{ records }` — lightweight | `POLL_INTERVAL × 3` |
| `poll:radarr-tags` | `[{ instance, data: [{id, label}] }]` | `POLL_INTERVAL × 3` |
| `poll:qbittorrent` | `[torrent, …]` | `POLL_INTERVAL × 3` |
| `history:sonarr` | `[record, …]` flat array with `_instanceUrl`/`_instanceName` | 5 min |
| `history:radarr` | `[record, …]` flat array with `_instanceUrl`/`_instanceName` | 5 min |
| `emby:users` | `Map<lowerName, displayName>` | 60 s |

When polling is disabled (`POLL_INTERVAL=0`), all `poll:*` TTLs fall back to **30 s** and data is fetched on-demand when the dashboard finds an empty cache entry.

### 6.3 Background Polling Modes

| Mode | `POLL_INTERVAL` | Behaviour |
|------|----------------|-----------|
| **Background** | `> 0` (e.g. `5000`) | Periodic fetch every N ms; SSE subscribers notified after each cycle |
| **On-demand** | `0` / `off` / `false` | Fetch triggered by first dashboard request when cache is empty; cached 30 s |

The poller uses a `polling` boolean flag to prevent concurrent cycles: if an interval fires while the previous poll is still running, the new invocation is skipped and logged.

### 6.4 Smart Polling Optimisation

When Sonarr/Radarr are configured to send webhooks to sofarr, the poller automatically reduces unnecessary API calls:

```
pollAllServices() called every POLL_INTERVAL ms:

  globalMetrics = cache.getGlobalWebhookMetrics()
  fallbackTriggered = lastGlobalWebhookTimestamp > WEBHOOK_FALLBACK_TIMEOUT ago

  for each service type (sonarr, radarr):
    shouldSkip = !fallbackTriggered
                 && all instances have metrics.eventsReceived > 0
                 && all instances have metrics.lastWebhookTimestamp within WEBHOOK_FALLBACK_TIMEOUT

    if shouldSkip:
      extend TTL of existing cached data        ← zero *arr API calls
      increment metrics.pollsSkipped
      log "[Poller] Skipping sonarr polling for N instance(s) with active webhooks"
    else:
      fetch from *arr APIs → update cache
```

**Effect:** zero *arr API calls per poll cycle when webhooks are active and recent. The poller automatically falls back to full polling after `WEBHOOK_FALLBACK_TIMEOUT` minutes of silence (default: 10 minutes), ensuring the dashboard remains accurate even if webhooks stop arriving.

### 6.5 Active SSE Client Tracking

SSE connections are tracked precisely in `activeClients` (a `Map` keyed by `${username}:${connectedAt}`): registered on connect, removed on disconnect. The admin status panel shows each connected user and their connection duration. The `type: 'sse'` field distinguishes SSE clients from other connection types.

---

## 7. Key Subsystems

### 7.1 Download Clients

See [Section 3.1](#31-pluggable-download-client-architecture-pdca) for full detail. The client hierarchy is:

```
DownloadClient (abstract — server/clients/DownloadClient.js)
├── SABnzbdClient.js       — Usenet; REST; API key auth
├── QBittorrentClient.js   — Torrent; Sync API + fallback; cookie auth
├── TransmissionClient.js  — Torrent; JSON-RPC; session-ID management
└── RTorrentClient.js      — Torrent; XML-RPC; HTTP Basic Auth
```

`server/utils/qbittorrent.js` is a legacy compatibility shim that delegates to `QBittorrentClient`.

### 7.2 Queue & History Processing

**`server/utils/historyFetcher.js`** fetches history records from all Sonarr/Radarr instances for a configurable date window. Results are cached under `history:sonarr` / `history:radarr` for 5 minutes. Exports `classifySonarrEvent` / `classifyRadarrEvent` (returns `'imported'` | `'failed'` | `'other'`) and `invalidateHistoryCache`.

**`server/routes/history.js`** (`GET /api/history/recent`) returns recently completed (imported or failed) downloads filtered for the authenticated user. Supports `?days=N` (default `RECENT_COMPLETED_DAYS`, capped at 90) and `?showAll=true` for admins. Results are sorted newest first.

**`server/routes/dashboard.js`** (`POST /api/dashboard/blocklist-search`) removes a Sonarr/Radarr queue item with `blocklist=true` and immediately triggers an `EpisodeSearch` or `MoviesSearch` command. Non-admin users may only blocklist when import issues are present, or (for qBittorrent only) the torrent is over 1 hour old with less than 100% availability.

### 7.3 Dashboard & Frontend

The frontend is a **vanilla JavaScript SPA** with no build step. All logic resides in `public/app.js`, styled by `public/style.css`, and structured by `public/index.html`. Three CSS themes are available via the `data-theme` attribute on `<html>` and persist in `localStorage`:

- **Light** — Purple gradient header, white cards
- **Dark** — Dark surfaces, muted accents
- **Mono** — Monochrome, minimal colour

#### UI state machine

```mermaid
stateDiagram-v2
    [*] --> SplashScreen : Page load
    SplashScreen --> CheckAuth : checkAuthentication()

    state CheckAuth <<choice>>
    CheckAuth --> LoginForm : No session
    CheckAuth --> Dashboard : Valid session

    LoginForm --> Dashboard : Auth success (fade transition)
    Dashboard --> LoginForm : Logout (stopSSE)

    state Dashboard {
        [*] --> Rendering
        Rendering --> Rendering : SSE message → renderDownloads()

        state SSEConnection {
            [*] --> Connecting
            Connecting --> Connected : First message
            Connected --> Reconnecting : Connection lost
            Reconnecting --> Connected : Auto-reconnect
            Connected --> Connecting : showAll toggled
        }

        state StatusPanel {
            [*] --> Closed
            Closed --> Open : Click Status (admin)
            Open --> Closed : Click close
            Open --> Open : 5s timer refresh
        }
    }
```

#### Key frontend functions

| Function | Purpose |
|----------|---------|
| `checkAuthentication()` | On load: check session → show dashboard or login |
| `handleLogin()` | Authenticate, fade login → splash → dashboard |
| `startSSE()` | Open `EventSource` to `/stream`; handle incoming data |
| `stopSSE()` | Close `EventSource` and cancel reconnect timer |
| `renderDownloads()` | Diff-based card rendering (create/update/remove); filters by selected download clients; sorts by client order |
| `createDownloadCard()` | Build DOM for a single card; renders tag badges, import-issue badge, blocklist button |
| `updateDownloadCard()` | Update existing card in-place (progress, speed, etc.) |
| `handleBlocklistSearch()` | Confirm dialog → POST `/blocklist-search` → update button state |
| `toggleStatusPanel()` | Show/hide admin status panel |
| `renderStatusPanel()` | Build status HTML (server, polling, SSE clients, cache) |
| `initThemeSwitcher()` | Light / Dark / Mono theme support |
| `loadHistory()` | Fetch `/api/history/recent`, store raw items, call `renderHistory()` |
| `renderHistory()` | Filter items by `ignoreAvailable` flag, render history cards |

#### Tag badge rendering

- **Regular user view** — a single accent-coloured badge showing the tag label that matched the current user's username (via `matchedUserTag`).
- **Admin `showAll` view** — all tags on the download are rendered using `tagBadges[]`: tags with no matching Emby user → amber badge (leftmost); tags matched to a known Emby user → accent badge showing the Emby display name (rightmost).

#### Download Client Filter

The Active Downloads tab includes a multi-select dropdown filter that allows users to:
- View all download clients with their type displayed as "Client Name (type)"
- Select multiple clients to filter the downloads list
- Use "Select All" / "Deselect All" buttons for bulk operations
- Persist selection across sessions via localStorage

Downloads are sorted by client order (matching the configuration order) and filtered by the selected client IDs.

Related functions:
- `initDownloadClientFilter()` — Sets up dropdown toggle, click-outside handler, Select/Deselect All buttons
- `updateDownloadClientFilter()` — Populates checkbox list with client name + type badges
- `toggleClientSelection()` — Updates selection array and localStorage
- `updateSelectedCountDisplay()` — Updates button text to show "All clients" / "1 selected" / "N selected"

---

## 8. Directory Structure

```
sofarr/
├── server/
│   ├── app.js                  Express app factory — imported by tests and index.js
│   ├── index.js                Entry point: logging setup, server listen, poller start
│   ├── clients/                PDCA — one file per download client + retriever
│   │   ├── DownloadClient.js   Abstract base class for all download clients
│   │   ├── QBittorrentClient.js
│   │   ├── SABnzbdClient.js
│   │   ├── TransmissionClient.js
│   │   ├── RTorrentClient.js
│   │   ├── PollingSonarrRetriever.js  PALDRA — Sonarr retriever
│   │   └── PollingRadarrRetriever.js  PALDRA — Radarr retriever
│   ├── routes/
│   │   ├── auth.js             POST /login, GET /me, GET /csrf, POST /logout
│   │   ├── dashboard.js        SSE /stream, /user-downloads, /user-summary, /status, /cover-art, /blocklist-search
│   │   ├── history.js          GET /api/history/recent
│   │   ├── webhook.js          POST /api/webhook/sonarr|radarr
│   │   ├── sonarr.js           Sonarr API proxy + webhook management
│   │   ├── radarr.js           Radarr API proxy + webhook management
│   │   ├── emby.js             Emby API proxy
│   │   └── sabnzbd.js          SABnzbd API proxy
│   ├── middleware/
│   │   ├── requireAuth.js      httpOnly cookie auth enforcement
│   │   └── verifyCsrf.js       Double-submit CSRF check (timing-safe)
│   └── utils/
│       ├── arrRetrievers.js    PALDRA registry — Sonarr/Radarr fetch registry
│       ├── cache.js            MemoryCache + webhook metrics helpers
│       ├── config.js           Multi-instance config parser
│       ├── downloadClients.js  PDCA registry + factory
│       ├── historyFetcher.js   History fetch + event classification
│       ├── logger.js           File logger (DATA_DIR/server.log)
│       ├── poller.js           Smart background polling engine
│       ├── qbittorrent.js      Legacy compatibility shim → QBittorrentClient
│       ├── sanitizeError.js    Secret redaction from errors/logs
│       └── tokenStore.js       Emby token store (JSON file, atomic writes, 31-day TTL)
├── public/                     Static SPA (served by Express)
│   ├── index.html              HTML shell: splash, login, dashboard
│   ├── app.js                  All frontend logic
│   ├── style.css               Themes, layout, responsive design
│   ├── favicon.ico / *.png     Favicons
│   └── images/                 Logo / splash screen assets
├── tests/
│   ├── README.md               Testing approach and coverage targets
│   ├── setup.js                Global setup: isolated DATA_DIR, rate-limit bypass
│   ├── unit/                   Pure unit tests (no HTTP)
│   └── integration/            Supertest + nock integration tests
├── .gitea/workflows/
│   ├── ci.yml                  Security audit + test/coverage on every push/PR
│   ├── build-image.yml         Docker image build and push
│   ├── create-release.yml      Release tagging workflow
│   ├── docs-check.yml          Markdown lint + Mermaid validation
│   └── licence-check.yml       Production dependency licence check
├── Dockerfile                  Multi-stage production image (node:22-alpine)
├── docker-compose.yaml         Example compose deployment
├── vitest.config.js            Test runner configuration with per-file coverage thresholds
├── package.json                Dependencies and scripts
├── ARCHITECTURE.md             This document
├── SECURITY.md                 Threat model and hardening guide
├── CHANGELOG.md                Version history
└── .env.sample                 Annotated environment variable template
```

---

## 9. Configuration and Environment Variables

### 9.1 Core Server

| Variable | Required | Default | Description |
|----------|:--------:|---------|-------------|
| `PORT` | No | `3001` | Server listen port |
| `NODE_ENV` | No | — | Set to `production` for production logging and startup validation |
| `DATA_DIR` | No | `./data` | Directory for `tokens.json` and `server.log`. Must be writable. In Docker: `/app/data` (named volume). |
| `COOKIE_SECRET` | No* | — | Signs all session cookies with HMAC-SHA256. **Strongly recommended in production** (server exits on startup if unset in `NODE_ENV=production`). Generate with `openssl rand -hex 32`. |
| `TRUST_PROXY` | No | — | Express `trust proxy` setting. Set to `1` when behind a TLS-terminating reverse proxy (nginx, Caddy, Traefik) so `req.ip` and `req.secure` are correct. |
| `LOG_LEVEL` | No | `info` | `debug`, `info`, `warn`, `error`, `silent` |
| `RECENT_COMPLETED_DAYS` | No | `7` | Default lookback window for `/api/history/recent`. Overridable per-request via `?days=`. Capped at 90. |

### 9.2 TLS / HTTPS

| Variable | Required | Default | Description |
|----------|:--------:|---------|-------------|
| `TLS_ENABLED` | No | `true` | Set to `false` to run plain HTTP (e.g. when TLS is terminated by a reverse proxy). |
| `TLS_CERT` | No | `certs/snakeoil.crt` | Path to TLS certificate (PEM). Defaults to the bundled self-signed snakeoil certificate. |
| `TLS_KEY` | No | `certs/snakeoil.key` | Path to TLS private key (PEM). |

### 9.3 Webhook

| Variable | Required | Default | Description |
|----------|:--------:|---------|-------------|
| `SOFARR_WEBHOOK_SECRET` | Yes* | — | Shared secret validated on the `X-Sofarr-Webhook-Secret` header. Webhook endpoints reject all requests if this is not set. Generate with `openssl rand -hex 32`. |
| `SOFARR_BASE_URL` | Yes* | — | Public base URL of this sofarr instance (e.g. `https://sofarr.example.com`). Used by the one-click webhook configuration endpoints to tell Sonarr/Radarr where to send events. |
| `WEBHOOK_FALLBACK_TIMEOUT` | No | `10` | Minutes of silence after which the poller falls back to full polling even when webhooks were recently active. |

### 9.4 Polling

| Variable | Required | Default | Description |
|----------|:--------:|---------|-------------|
| `POLL_INTERVAL` | No | `5000` | Background poll interval in ms. Set to `0`, `off`, or `false` to disable and use on-demand mode. |

### 9.5 Emby

| Variable | Required | Default | Description |
|----------|:--------:|---------|-------------|
| `EMBY_URL` | Yes | — | Emby/Jellyfin base URL (e.g. `https://emby.example.com`) |
| `EMBY_API_KEY` | Yes | — | Emby API key — used by the poller to list users for tag badge classification |

### 9.6 Service Instances

All service instances support both a JSON array format (recommended) and a legacy single-instance format:

| Variable | Required | Format |
|----------|:--------:|--------|
| `SONARR_INSTANCES` | Yes* | JSON array |
| `SONARR_URL` + `SONARR_API_KEY` | Yes* | Legacy single-instance |
| `RADARR_INSTANCES` | Yes* | JSON array |
| `RADARR_URL` + `RADARR_API_KEY` | Yes* | Legacy single-instance |
| `SABNZBD_INSTANCES` | Yes* | JSON array |
| `SABNZBD_URL` + `SABNZBD_API_KEY` | Yes* | Legacy single-instance |
| `QBITTORRENT_INSTANCES` | No | JSON array (uses `username`/`password` not `apiKey`) |
| `RTORRENT_INSTANCES` | No | JSON array (URL must include the full XML-RPC path, e.g. `/RPC2`) |

\* Either `*_INSTANCES` or the legacy pair is required for each service.

#### JSON array instance format

```json
[
  { "name": "main", "url": "https://sonarr.example.com", "apiKey": "your-api-key" },
  { "name": "4k",   "url": "https://sonarr4k.example.com", "apiKey": "your-4k-api-key" }
]
```

qBittorrent and rTorrent instances use `username` and `password` instead of `apiKey`.

Each instance receives an `id` derived from `name` (or index if unnamed), used as the key in PDCA and PALDRA registries.

---

## 10. Security Model

### 10.1 Authentication and Sessions

| Concern | Mechanism |
|---------|-----------|
| **User authentication** | Emby credentials via `POST /Users/authenticatebyname`. A deterministic `DeviceId` (SHA-256 of username, first 16 chars) ensures Emby reuses the same session on every login. |
| **Session cookie** | `httpOnly`, `sameSite: strict`, `secure` when `TRUST_PROXY` is set. Payload: `{ id, name, isAdmin }` only — the Emby `AccessToken` is **never** sent to the browser. Signed with HMAC when `COOKIE_SECRET` is set. |
| **Token store** | Emby `AccessToken`s stored server-side in `DATA_DIR/tokens.json` (atomic writes, 31-day TTL, hourly pruning). Used only for server-side Emby logout. |
| **Session validation** | `requireAuth` middleware on all `/api/dashboard`, `/api/history`, and proxy routes. Returns `401` if the cookie is absent, tampered, or schema-invalid. |
| **CSRF protection** | Double-submit cookie pattern. `verifyCsrf` middleware compares the `csrf_token` cookie against the `X-CSRF-Token` request header using `crypto.timingSafeEqual`. Applied to all state-changing requests (`POST`, `PUT`, `PATCH`, `DELETE`) under `/api/*` except auth and webhook routes. |
| **Remember-me** | `rememberMe: true` → persistent cookie, `Max-Age` 30 days. `rememberMe: false` → session cookie (expires on browser close). |

### 10.2 Webhook Security

| Concern | Mechanism |
|---------|-----------|
| **Secret validation** | Every webhook request must carry `X-Sofarr-Webhook-Secret` matching `SOFARR_WEBHOOK_SECRET`. Absent or wrong secret → `401`. Webhook endpoints function outside the CSRF middleware (they are not browser-initiated). |
| **Rate limiting** | Dedicated `webhookLimiter`: 60 req/min per IP (stricter than the general 300 req/15 min limiter). |
| **Payload validation** | `validatePayload()` enforces: JSON object body, `eventType` as a non-empty string ≤ 64 chars, `eventType` in the allowlist, `instanceName` as string if present. Rejects with `400` on any violation. |
| **Replay protection** | `isReplay()` caches a composite key `{eventType}:{instanceName}:{date}` for 5 minutes. Duplicate events within that window are acknowledged with `200 { received: true, duplicate: true }` and not processed. |

### 10.3 Additional Security Measures

| Concern | Mechanism |
|---------|-----------|
| **Rate limiting** | 300 req/15 min general (all API routes); 10 failed attempts/15 min login limiter; 60 req/1 min webhook limiter. |
| **Secret leakage** | `sanitizeError()` (`server/utils/sanitizeError.js`) redacts secrets from error messages and logs: URL query-param secrets (`apikey=`, `token=`), HTTP auth headers (`Authorization:`, `X-Emby-Authorization:`), Bearer tokens, and basic-auth credentials in URLs. |
| **HTTP headers** | Helmet v7: CSP with per-request nonce (`crypto.randomBytes(16)` for inline styles/scripts), HSTS, `X-Frame-Options: DENY`, `X-Content-Type-Options: nosniff`, `Referrer-Policy`, `Permissions-Policy`. |
| **Body size** | `express.json` body limit: 64 KB. |
| **Authorisation matrix** | Regular users see only their own downloads. Admins can view all users, see paths and *arr links, and blocklist any download. Non-admins can only blocklist when import issues exist or (for qBittorrent) the torrent is >1 h old with <100% availability. |
| **Container security** | Docker image runs as the non-root `node` user (UID 1000). `/app/data` is owned by `node`. |

---

## 11. Technology Stack

### Runtime and Framework

| Layer | Technology | Notes |
|-------|-----------|-------|
| Runtime | Node.js 22 (Alpine) | LTS; ESM-ready; V8 coverage built-in |
| Framework | Express 4.x | HTTP server, routing, middleware |
| HTTP client | axios 1.x | External API communication |
| XML-RPC client | xmlrpc 1.3.2 | rTorrent communication |
| Frontend | Vanilla JS + CSS | SPA, no build step required |
| Containerisation | Docker multi-stage (node:22-alpine) | Non-root `node` user; minimal image |
| Logging | Custom logger + `console.*` redirection | File + stdout with configurable levels |

### Security Middleware

| Package | Version | Purpose |
|---------|---------|---------|
| `helmet` | 7.x | HTTP security headers (CSP nonce, HSTS, referrer policy, frame options) |
| `express-rate-limit` | 7.x | General, login, and webhook rate limiters |
| `cookie-parser` | 1.x | Signed cookie support (HMAC via `COOKIE_SECRET`) |

### Auth and Session

| Component | Technology | Details |
|-----------|-----------|---------|
| Identity provider | Emby / Jellyfin API | `POST /Users/authenticatebyname` |
| Session cookie | `httpOnly` + `sameSite: strict` | Signed when `COOKIE_SECRET` is set |
| CSRF protection | Double-submit cookie | `csrf_token` cookie + `X-CSRF-Token` header; `crypto.timingSafeEqual` |
| Token store | JSON file (`DATA_DIR/tokens.json`) | Atomic writes, 31-day TTL, hourly pruning |

### Testing

| Tool | Version | Purpose |
|------|---------|---------|
| `vitest` | 4.x | Test runner with V8 coverage; per-file coverage thresholds in `vitest.config.js` |
| `supertest` | 7.x | HTTP integration testing against the Express app factory |
| `nock` | 14.x | HTTP interception at Node layer (compatible with CJS `require('axios')`) |

### CI/CD

| Workflow file | Trigger | Purpose |
|---------------|---------|---------|
| `ci.yml` | Every push / PR | `npm audit --audit-level=high` + full test suite with V8 coverage |
| `build-image.yml` | Push to `release/**` or `develop` | Build and push Docker image to registry |
| `create-release.yml` | Tag push (`v*`) | Generate release notes and create a Gitea release |
| `docs-check.yml` | Push / PR touching `**.md` | Markdown lint + Mermaid diagram parse validation |
| `licence-check.yml` | Push / PR touching `package.json` | Verify production dependency licences are MIT-compatible |