# Download Manager & Offline Architecture

## Overview

Location: `src-tauri/src/download/`

The download manager provides offline media support with priority-based queue management, progress tracking, retry logic, and smart caching.

    flowchart TB
        subgraph Frontend["Frontend"]
            DownloadButton["DownloadButton.svelte"]
            DownloadsPage["/downloads"]
            DownloadsStore["downloads.ts store"]
        end

        subgraph Backend["Rust Backend"]
            Commands["Download Commands"]
            DownloadManager["DownloadManager"]
            DownloadWorker["DownloadWorker"]
            SmartCache["SmartCache Engine"]
        end

        subgraph Storage["Storage"]
            SQLite[("SQLite DB")]
            MediaFiles[("Downloaded Files")]
        end

        DownloadButton -->|"invoke('download_item')"| Commands
        DownloadsPage -->|"invoke('get_downloads')"| Commands
        Commands --> DownloadManager
        DownloadManager --> DownloadWorker
        DownloadManager --> SmartCache
        DownloadWorker -->|"HTTP Stream"| MediaFiles
        DownloadWorker -->|"Events"| DownloadsStore
        Commands <--> SQLite
        SmartCache <--> SQLite

## Download Worker

Location: `src-tauri/src/download/worker.rs`

The download worker handles HTTP streaming with retry logic and resume support:

    #![allow(unused)]
    fn main() {
    pub struct DownloadWorker {
        client: reqwest::Client,
        max_retries: u32,
    }

    pub struct DownloadTask {
        pub id: i64,
        pub item_id: String,
        pub user_id: String,
        pub priority: i32,
        pub url: String,
        pub target_path: PathBuf,
        pub mime_type: Option<String>,
        pub expected_size: Option<i64>,
    }
    }

Retry Strategy:

- Exponential backoff: 5s, 15s, 45s
- Maximum 3 retry attempts
- HTTP Range requests for resume support
- Progress events emitted every 1MB

Download Flow:

    sequenceDiagram
        participant UI
        participant Command as download_item
        participant DB as SQLite
        participant Worker as DownloadWorker
        participant Jellyfin as Jellyfin Server
        participant Store as downloads store

        UI->>Command: download_item(itemId, userId)
        Command->>DB: INSERT INTO downloads
        Command->>Worker: Start download task
        Worker->>Jellyfin: GET /Items/{id}/Download

        loop Progress Updates
            Jellyfin->>Worker: Stream chunks
            Worker->>Worker: Write to .part file
            Worker->>Store: Emit progress event
            Store->>UI: Update progress bar
        end

        Worker->>Worker: Rename .part to final
        Worker->>DB: UPDATE status='completed'
        Worker->>Store: Emit completed event
        Store->>UI: Show completed

## Smart Caching Engine

Location: `src-tauri/src/download/cache.rs`

The smart caching system provides predictive downloads based on listening patterns:

    #![allow(unused)]
    fn main() {
    pub struct SmartCache {
        config: Arc<Mutex<CacheConfig>>,
        album_play_history: Arc<Mutex<HashMap<String, Vec<String>>>>,
    }

    pub struct CacheConfig {
        pub queue_precache_enabled: bool,
        pub queue_precache_count: usize,        // Default: 5
        pub album_affinity_enabled: bool,
        pub album_affinity_threshold: usize,    // Default: 3
        pub storage_limit: u64,                 // Default: 10GB
        pub wifi_only: bool,                    // Default: true
    }
    }

Caching Strategies:

1. Queue Pre-caching: Auto-download next 5 tracks when playing (WiFi only)
2. Album Affinity: If user plays 3+ tracks from album, cache entire album
3. LRU Eviction: Remove least recently accessed when storage limit reached

    flowchart TB
        Play["Track Played"] --> CheckQueue{"Queue<br/>Pre-cache?"}
        CheckQueue -->|"Yes"| CacheNext5["Download<br/>Next 5 Tracks"]

        Play --> TrackHistory["Track Play History"]
        TrackHistory --> CheckAlbum{"3+ Tracks<br/>from Album?"}
        CheckAlbum -->|"Yes"| CacheAlbum["Download<br/>Full Album"]

        CacheNext5 --> CheckStorage{"Storage<br/>Limit?"}
        CacheAlbum --> CheckStorage
        CheckStorage -->|"Exceeded"| EvictLRU["Evict LRU Items"]
        CheckStorage -->|"OK"| Download["Queue Download"]

## One Storage Model: Cache Entries Are Downloads

TRACES: UR-071 | DR-126, DR-127

A cache entry is a download with a shorter life: the same `downloads` row and the same file handling, distinguished by `download_source` plus an expiry. There is one storage model rather than a cache and a download library that can disagree about what is on disk.

`download_source` | Life | Reclaimed by
--- | --- | ---
`'auto'` (temporary) | Expiry, or eviction under space pressure | Both
`'user'` (permanent) | No expiry | Neither

Eviction only reclaims the temporary tier. `evict_lru_async` originally selected every completed download ordered by `completed_at ASC` with no source filter, so hitting the storage limit deleted the oldest download — typically a film saved deliberately for offline — to make room for a newly precached track. It now evicts only `COALESCE(download_source, 'user') = 'auto'` rows. `COALESCE` rather than a bare equality is load-bearing: rows predating the migration can be NULL, and unknown provenance must be treated as the user's, never as disposable. Freeing less than requested is the correct outcome when only user downloads remain — the caller reports "unable to free enough".

A temporary row can be promoted to permanent when the user chooses to keep it. That only clears the expiry and flips the source; the bytes never move.

## Offline Catalog Visibility

TRACES: UR-052 | DR-078, DR-079, DR-080

Offline, a library page shows only media on the device. A "Show all server media" toggle additionally reveals the cached server catalog, greyed out and queueable for download on reconnect.

The gate is a process-global `INCLUDE_CATALOG_BROWSE` in `repository/offline.rs`, written by the `set_show_server_catalog` command. It gates the synced-catalog leg of `get_items`; without it the toggle rendered but every server item still appeared, which is the defect the spec was written for. `isConnected` derives from backend-reported reachability alone (DR-079) — see 07-connectivity.md.

Per-item disk usage comes from `repository_get_download_disk_usage` (`DownloadDiskUsage`), aggregated from `downloads.file_size` — used by the Downloaded browse cards, detail pages, the device total and the remove confirmation (DR-085).

## Download Commands

Location: `src-tauri/src/commands/download/` — `mod.rs` (the commands below), `pinning.rs`, `smart_cache.rs`

Command | Parameters | Description
--- | --- | ---
`download_item` | `item_id, user_id, file_path` | Queue single item download
`download_album` | `album_id, user_id` | Queue all tracks in album
`get_downloads` | `user_id, status_filter` | Get download list
`pause_download` | `download_id` | Pause active download
`resume_download` | `download_id` | Resume paused download
`cancel_download` | `download_id` | Cancel and delete partial
`delete_download` | `download_id` | Delete completed download
`download_video` / `download_series` / `download_season` | item ids | Queue video content
`get_download_storage_stats` | `user_id` | Device totals for the downloads screen
`delete_album_downloads` / `delete_downloads_under` / `delete_all_downloads` | container id | Bulk removal
`pin_item` / `unpin_item` / `is_item_pinned` | `item_id` | Protect metadata from a cache clear
`set_max_concurrent_downloads` | `max` | Worker concurrency (3 by default)

## Offline Commands

Location: `src-tauri/src/commands/offline.rs`

Command | Parameters | Description
--- | --- | ---
`offline_is_available` | `item_id` | Check if item downloaded
`offline_get_items` | `user_id` | Get all offline items
`offline_search` | `user_id, query` | Search downloaded items

## Player Integration

Location: `src-tauri/src/commands/player.rs` (modified)

The player checks for local downloads before streaming:

    #![allow(unused)]
    fn main() {
    fn create_media_item(req: PlayItemRequest, db: Option<&DatabaseWrapper>) -> MediaItem {
        let local_path = db.and_then(|db_wrapper| {
            check_for_local_download(db_wrapper, &jellyfin_id).ok().flatten()
        });

        let source = if let Some(path) = local_path {
            MediaSource::Local {
                file_path: PathBuf::from(path),
                jellyfin_item_id: Some(jellyfin_id.clone())
            }
        } else {
            MediaSource::Remote {
                stream_url: req.stream_url,
                jellyfin_item_id: jellyfin_id.clone()
            }
        };

        MediaItem { source, /* ... */ }
    }
    }

## Frontend Downloads Store

Location: `src/lib/stores/downloads.ts`

    interface DownloadsState {
      downloads: Record<number, DownloadInfo>;
      activeCount: number;
      queuedCount: number;
    }

    const downloads = createDownloadsStore();

    // Actions
    downloads.downloadItem(itemId, userId, filePath)
    downloads.downloadAlbum(albumId, userId)
    downloads.pause(downloadId)
    downloads.resume(downloadId)
    downloads.cancel(downloadId)
    downloads.delete(downloadId)
    downloads.refresh(userId, statusFilter)

    // Derived stores
    export const activeDownloads = derived(downloads, ($d) =>
      Object.values($d.downloads).filter((d) => d.status === 'downloading')
    );

Event Handling:

The store listens to Tauri events for real-time updates:

    listen<DownloadEvent>('download-event', (event) => {
      const payload = event.payload;

      switch (payload.type) {
        case 'started':
          // Update status to 'downloading'
        case 'progress':
          // Update progress and bytes_downloaded
        case 'completed':
          // Update status to 'completed', progress to 1.0
        case 'failed':
          // Update status to 'failed', store error message
      }
    });

## Download UI Components

DownloadButton (`src/lib/components/library/DownloadButton.svelte`):

- Multiple states: available, downloading, completed, failed, paused
- Circular progress ring during download
- Size variants: sm, md, lg
- Integrated into TrackList with `showDownload={true}` prop

DownloadItem (`src/lib/components/downloads/DownloadItem.svelte`):

- Individual download list item with progress bar
- Action buttons: pause, resume, cancel, delete
- Status indicators with color coding

Downloads Page (`src/routes/downloads/+page.svelte`):

- Active/Completed tabs
- Bulk actions: Pause All, Resume All, Clear Completed
- Empty states with helpful instructions

## Database Schema

downloads table:

    CREATE TABLE downloads (
        id              INTEGER PRIMARY KEY AUTOINCREMENT,
        item_id         TEXT NOT NULL,
        user_id         TEXT NOT NULL,
        file_path       TEXT,
        file_size       INTEGER,
        mime_type       TEXT,
        status          TEXT DEFAULT 'pending',  -- pending, downloading, completed, failed, paused
        progress        REAL DEFAULT 0.0,
        bytes_downloaded INTEGER DEFAULT 0,
        priority        INTEGER DEFAULT 0,
        error_message   TEXT,
        retry_count     INTEGER DEFAULT 0,
        queued_at       TEXT DEFAULT CURRENT_TIMESTAMP,
        started_at      TEXT,
        completed_at    TEXT
    );

    CREATE INDEX idx_downloads_queue
      ON downloads(status, priority DESC, queued_at ASC)
      WHERE status IN ('pending', 'downloading');