Sonarr as a Policy-Driven Reconciliation System
Sonarr is best understood not as a downloader with a friendly interface, but as a long-lived reconciliation system for an episodic media library. This final synthesis answers the central question raised by the project: how can an application keep a desired library aligned with release feeds, external download clients, and local files when none of those outside systems is fully under its control? The resulting model lets a reader judge Sonarr's strengths, its conservative boundaries, and the operational questions that the repository cannot answer on its own.
The answer is a loop. Sonarr stores what the library is supposed to contain, observes what external systems currently report, applies the reader's policy, changes state only when the evidence is sufficient, and records the outcome so the next cycle is informed by the last one. The loop is not a metaphor that replaces the software's mechanisms. It is the relationship those mechanisms create across metadata, parsing, discovery, decision, execution, import, and memory.
The real unit of work is a justified state change
A linear download pipeline might be described as “find a release, download it, and put it in a folder.” That description omits the questions that make each transition safe. Which series and episode does the release represent? Is that episode in scope? Is the candidate acceptable for this series? Is it an upgrade or a duplicate? Can the configured client accept it? When the client finishes, can Sonarr read the path and map every file correctly?
Sonarr's durable model gives those questions a common reference. A series carries identity, metadata, path, monitoring, tags, and a quality-profile association. Episodes belong to series and carry numbering, dates, monitoring, and an optional file relationship. Episode files record the observed library result: path, size, quality, language, media information, and release provenance. The distinction between an episode and its file is essential. The episode expresses what the library may need; the file expresses what the library currently has.
External observations are different again. An indexer supplies release reports. A download client supplies items with titles, identifiers, statuses, sizes, paths, and capabilities. The filesystem supplies files and folders that may be incomplete, locked, misnamed, or mixed with unrelated content. Sonarr's job is to compare these observations with the durable model, not to confuse any one observation with the model itself.
This explains why an empty file relationship is meaningful but limited. Within Sonarr's current library state, it can mean that an episode is missing a suitable file. It does not prove that nobody has downloaded the episode, that no file exists elsewhere, or that an upstream metadata record is complete. The system must continue observing because internal records and external reality can drift.
The same principle explains why an accepted decision is not yet a library result. A decision is an internal judgment about a candidate. A client acceptance is evidence that an external system took responsibility for the work. An imported episode file is a later, stronger state transition. Sonarr's architecture keeps these transitions separate because each one has a different owner and a different failure surface.
One episode reveals the whole loop
Consider a series that a reader has added to Sonarr and an episode that should be maintained. Metadata acquisition establishes the series identity and supplies the episode record. The local configuration supplies the path, monitoring choice, and quality profile. At this point Sonarr has a desired state, not a downloaded file.
An RSS feed or explicit search then supplies a release report. The report contains a title and other fields, but the title is an external naming convention rather than a canonical episode record. Sonarr parses it, extracts a possible series and episode identity, and preserves separate evidence for dates, absolute numbers, quality, languages, release group, hash, and revision. If the naming form is ambiguous or unusable, the report stops before it can alter the library.
If identity mapping succeeds, the release becomes a remote episode associated with known series and episode records. The indexer contributed a candidate; it did not decide that the candidate belongs in the library. Sonarr's decision specifications then check the candidate against current monitoring, history, quality, custom formats, protocol, delays, restrictions, and resource conditions. A candidate can be understood and still be rejected. It can be understood and temporarily held. It can pass the gates and still be only eligible for submission.
The control plane carries that result into a command and provider boundary. The scheduler, queue, and executor determine when compatible work can run. Provider factories resolve a configured indexer or download client from a durable definition and a common contract. The download service selects a client compatible with the release's protocol, indexer, tags, and availability, and can try a distinct configured client if the first route fails. Only after a client accepts the release does Sonarr publish the grab event that downstream tracking can use.
The external client then becomes the source of a new observation. Sonarr polls the client, creates or updates a tracked download, and reconstructs the remote episode context from the current item and stored history. If the client title has lost information, the original source title and grabbed episode identifiers can help restore the association. If the evidence remains insufficient, Sonarr keeps the item visible and blocks automatic import rather than choosing a series by guesswork.
When the client reports completion, Sonarr begins another decision process. It checks the output path, operating-system compatibility, file accessibility, naming and folder context, file extensions, locks, samples, extras, and episode mapping. It aggregates file size, media information, quality, language, release provenance, and custom-format evidence.