Concepts

Concepts

Use this page as the vocabulary reference for the rest of the docs. Each term is defined the way it’s used in the UI and across these docs — intentionally product-specific.

Core Model

Instance

An instance is one running Weaver server with its own database, configuration, storage paths, queue, and web UI.

In practice that means the web app you open in the browser, the service Docker or Homebrew manages, and the GraphQL API behind that UI.

For example, a Docker container with /config, /downloads/intermediate, and /downloads/complete mounted is one Weaver instance.

Job

Every NZB you submit becomes a job: one unit of work tracked by Weaver. You’ll work with jobs everywhere — Queue, Job Detail, History, Monitoring, and Logs.

Jobs move through status states such as queued, downloading, verifying, repairing, extracting, moving, complete, failed, or paused.

For example, uploading one NZB creates one job row that you can pause, resume, open, or filter, and that moves into history after completion.

Queue

The queue is the live list of jobs Weaver is still tracking as active work. You’ll find it at the root route and as Queue in the left navigation.

It’s where jobs meet global pause, speed limits, categories, server availability, and the bandwidth cap.

For example, a queued job can hold position while the instance is globally paused.

Job Detail

Job Detail is the page for one job: status, progress, speed, ETA, saved bandwidth, output files, release metadata, and event logs where available.

Open it from any Queue or History row.

Head there when a single job needs closer inspection or a targeted pause, resume, cancel, delete, reprocess, or diagnostic action.

Upload

Upload is where you submit one or more of your own NZB files to Weaver.

You’ll reach it through the persistent Upload button or the /upload route. Staged files, password fields, category selection, and priority all come together here to create queue jobs.

For example, uploading three NZB files with the same category creates three jobs with shared upload settings.

NZB

An NZB is the job descriptor file you hand to Weaver. Weaver stores and processes it as input to a job.

For example, the Upload dialog accepts .nzb files and optional shared metadata before creating jobs.

Server

A server is a configured connection record Weaver can use during job processing.

You manage servers in Settings > Servers; each record stores host, port, TLS, credentials, connection count, active state, and group.

For example, you can disable a server while keeping its configuration for later testing.

Server Group

A server group controls priority between configured server records. Group 0 is primary; higher groups are backfill.

You set groups in Settings > Servers, and they decide how Weaver orders configured connections.

For example, put primary records in group 0 and reserve group 1 for backfill records.

Category

A category is a named routing label with optional aliases and a destination directory override.

You’ll use categories in Upload, Queue, History, Settings > Categories, and RSS rule configuration.

For example, a category named tv can map accepted jobs into a specific complete directory.

History

History is the record of completed and failed jobs, under History in the left navigation.

It’s separate from Queue: Queue is live work, while History is the retained operational record.

For example, a completed job leaves Queue and lands in History with status, health, size, category, and actions.

Storage And Pipeline

Data Directory

The data directory stores Weaver’s database, job cache, configuration state, API keys, RSS state, and internal runtime state.

You’ll see it in Settings > General and in Docker or release-binary installation examples.

For example, a Docker volume mounted at /config keeps the instance state across container upgrades.

Intermediate Directory

The intermediate directory stores active per-job work before final movement.

Set it in Settings > General, and keep it on storage Weaver can read and write reliably.

For example, put intermediate work on fast local storage when post-processing shouldn’t compete with final library storage.

Complete Directory

The complete directory is where Weaver places finished output after successful processing and category routing.

You configure it in Settings > General and Settings > Categories.

For example, a category can override the default complete directory for jobs assigned to that category.

Cleanup After Extract

Cleanup after extract controls whether Weaver removes intermediate files after a successful extraction.

You toggle it in Settings > General; it directly affects intermediate storage pressure.

Enable cleanup when you want successful jobs to leave only final output in the complete directory.

Retry

Retry is Weaver’s configured attempt limit for failed article work before a job is marked permanently failed.

You set it in Settings > General as Max Retries, and you’ll see it in job events when failures occur.

For example, raising max retries can give unstable connections more attempts before the job fails.

Verify, Repair, Extract, And Move

Verify, repair, extract, and move are the post-processing stages you’ll see in job status, Job Detail, Monitoring, and event logs.

They make up the job pipeline after Weaver has processed the article data.

For example, a job can be downloading in Queue, then verifying, repairing, extracting, and moving before it reaches History.

Global Pause

Global pause blocks new download dispatch for queued and downloading jobs while allowing some already-running post-processing stages to continue.

You control it from the Queue header with Pause All and Resume All.

Pause All before maintenance on server connections, then Resume All when the instance is ready.

Speed Limit

Speed limit is the current and persisted download ceiling Weaver applies to active work.

You can set it from Queue and in Settings > General.

For example, set a temporary speed limit from Queue, then review the persisted setting in General.

Bandwidth Cap

Bandwidth cap tracks a configured allowance window and blocks new download dispatch when the window is exhausted.

You configure it in Settings > ISP Bandwidth Cap and see its state in Queue warning banners and Monitoring.

For example, a monthly cap can hold queued jobs until the configured reset day and time.

Automation And Integration

RSS Feed

An RSS feed is a configured feed record Weaver can poll according to its schedule and rules.

You manage feeds in Settings > RSS. The docs only cover the Weaver-side feed URL, auth, category, metadata, polling, and state fields.

For example, a disabled feed remains configured but is skipped by scheduled and manual sync.

RSS Rule

An RSS rule is an ordered accept or reject policy attached to a feed.

You build rules in Settings > RSS; each can evaluate item title regex, feed categories, size range, category override, and metadata.

For example, a reject rule with a lower sort order can stop matching items before later accept rules run.

Seen History

Seen History is the per-feed record of RSS item decisions such as submitted, ignored, rejected, or error.

You’ll find it inside each feed card in Settings > RSS.

Clear seen history only when you intentionally want Weaver to reconsider previously seen feed items.

Schedule

A schedule is a recurring rule that pauses, resumes, or sets a speed limit at a configured time and day set.

You create schedules in Settings > Schedules.

For example, a weekday evening schedule can set a lower speed limit during a local maintenance window.

API Key

An API key is a credential for integrations using Weaver’s GraphQL API.

You create keys in Settings > Security; each has a scope such as read, integration, or admin.

Create an integration-scoped API key for Scryer instead of sharing an admin credential.

GraphQL API

The GraphQL API is Weaver’s primary integration surface at /graphql.

It powers the web UI’s own data flow, works with the API keys you create in Security, and is covered in the API and Metrics docs.

For example, an integration can read queue state through GraphQL using an appropriate API key.

Metrics Endpoint

The metrics endpoint exposes Prometheus-compatible metrics at /metrics.

It should normally stay on a private monitoring network; the API and Metrics docs cover it.

For example, Prometheus can scrape /metrics to track queue throughput and failure counters.

Operations

Monitoring

Monitoring is where you watch live and historical metrics: queue pressure, throughput, bandwidth cap state, and pipeline stages.

You’ll find it under Monitoring in the left navigation, and it works alongside Queue, Settings > ISP Bandwidth Cap, and the /metrics endpoint.

Use Monitoring to see whether active jobs are waiting on queue pressure, write buffering, or cap state.

Logs

The Logs page shows Weaver service log lines.

It gives you live mode, paused inspection, and text filtering for troubleshooting.

Pause live mode, filter for a job name, then compare the relevant lines to Job Detail events.

Diagnostic Re-run

A diagnostic re-run is a troubleshooting action for history jobs that creates a diagnostic-oriented run and optional bundle.

You’ll see it in History when diagnostic support is enabled.

Start a diagnostic re-run for a failed job before sharing troubleshooting details with maintainers.

Delete Operation

A delete operation is Weaver’s background work to remove a retained history record and, optionally, associated output files.

You’ll see it in History and Job Detail when a delete is queued, running, failed, or locked.

For example, a history row can stay visible while a delete operation finishes in the background.

Backup

A backup is an exported archive of Weaver’s stable state, including configuration, history, RSS state, and SQLite-backed settings.

You export one from Settings > Backup. Active jobs and payload files are not included.

Export a backup before moving an instance to new storage.

Restore

Restore imports a backup into an eligible instance after analysis and path remapping.

You run it from Settings > Backup, and it can replace current configuration, API keys, RSS state, and history.

For example, restore into a clean instance, remapping category paths that lived outside the old complete directory.

Base URL

Base URL is Weaver’s configured web path prefix when it runs behind a reverse proxy subpath.

You set it during reverse proxy setup, and it affects asset paths, routes, GraphQL, and WebSocket connections.

For example, serving Weaver at /weaver/ requires both the command-line base URL and the proxy path to agree.

Easy-To-Confuse Pairs

Pair	Difference
Queue vs History	Queue is active work. History is retained completed or failed work.
Job vs NZB	The NZB is submitted input. The job is Weaver’s tracked work record created from it.
Category vs directory	A category is a label and routing rule. A directory is the filesystem destination it may choose.
Speed limit vs bandwidth cap	Speed limit controls rate. Bandwidth cap controls window allowance and dispatch blocking.
Global pause vs job pause	Global pause affects dispatch across the queue. Job pause affects one selected job.
Backup vs payload files	Backups include stable state and settings. They do not include active job payload files.