# JellyTau Software Architecture

This document describes the current architecture of JellyTau, a cross-platform Jellyfin client built with Tauri, SvelteKit, and Rust.

**Last Updated:** 2026-03-01

## Architecture Overview

JellyTau uses a modern client-server architecture with a thin Svelte UI layer and comprehensive Rust backend:

### Architecture Principles

- **Thin UI Layer**: TypeScript reduced from ~3,300 to ~800 lines
- **Business Logic in Rust**: Performance, reliability, type safety
- **Event-Driven**: Rust emits events, TypeScript listens and updates UI
- **Handle-Based Resources**: UUID handles for stateful Rust objects
- **Cache-First**: Parallel queries with intelligent fallback

```mermaid
flowchart TB
    subgraph Frontend["Svelte Frontend"]
        subgraph Stores["Stores (Thin Wrappers)"]
            auth["auth"]
            player["player"]
            queue["queue"]
            library["library"]
            connectivity["connectivity"]
            playbackMode["playbackMode"]
        end
        subgraph Components
            playerComp["player/"]
            libraryComp["library/"]
            Search["Search"]
        end
        subgraph Routes
            routeLibrary["/library"]
            routePlayer["/player"]
            routeRoot["/"]
        end
        subgraph API["API Layer (Thin Client)"]
            RepositoryClient["RepositoryClient<br/>(Handle-based)"]
            JellyfinClient["JellyfinClient<br/>(Helper)"]
        end
    end

    Frontend -->|"Tauri IPC (invoke)"| Backend

    subgraph Backend["Rust Backend (Business Logic)"]
        subgraph Commands["Tauri Commands (90+)"]
            PlayerCmds["player.rs"]
            RepoCmds["repository.rs (27)"]
            PlaybackModeCmds["playback_mode.rs (5)"]
            StorageCmds["storage.rs"]
            ConnectivityCmds["connectivity.rs (7)"]
        end

        subgraph Core["Core Modules"]
            MediaSessionManager["MediaSessionManager<br/>(Audio/Movie/TvShow/Idle)"]

            PlayerController["PlayerController<br/>+ PlayerBackend<br/>+ QueueManager"]

            Repository["Repository Layer<br/>HybridRepository (cache-first)<br/>OnlineRepository (HTTP)<br/>OfflineRepository (SQLite)"]

            PlaybackModeManager["PlaybackModeManager<br/>(Local/Remote/Idle)"]

            ConnectivityMonitor["ConnectivityMonitor<br/>(Adaptive polling)"]

            HttpClient["HttpClient<br/>(Exponential backoff retry)"]
        end

        subgraph Storage["Storage Layer"]
            DatabaseService["DatabaseService<br/>(Async trait)"]
            SQLite["SQLite Database<br/>(13 tables)"]
        end

        Commands --> Core
        Core --> Storage
        Repository --> HttpClient
        Repository --> DatabaseService
    end
```

---

## Detailed Documentation

Each major subsystem is documented in its own file under [docs/architecture/](docs/architecture/):

| Document | Contents |
|----------|----------|
| [01 - Rust Backend](docs/architecture/01-rust-backend.md) | Media session state machine, player state machine, playback mode, media items, queue manager, favorites, player backend trait, player controller, playlist system, Tauri commands |
| [02 - Svelte Frontend](docs/architecture/02-svelte-frontend.md) | Store structure, music library navigation, playback reporting, repository architecture, playback mode system, database service abstraction, component hierarchy, MiniPlayer, sleep timer, auto-play, navigation guard, playlist management UI |
| [03 - Data Flow](docs/architecture/03-data-flow.md) | Repository query flow (cache-first), playback initiation, playback mode transfer, queue navigation, volume control |
| [04 - Type Sync & Threading](docs/architecture/04-type-sync-and-threading.md) | Rust/TypeScript type synchronization, Tauri v2 IPC parameter naming convention, thread safety patterns |
| [05 - Platform Backends](docs/architecture/05-platform-backends.md) | Player events system, MpvBackend (Linux), ExoPlayerBackend (Android), MediaSession & remote volume, album art caching, backend initialization |
| [06 - Downloads & Offline](docs/architecture/06-downloads-and-offline.md) | Download manager, download worker, smart caching engine, download/offline commands, player integration, frontend store, UI components |
| [07 - Connectivity](docs/architecture/07-connectivity.md) | HTTP client with retry logic, connectivity monitor, network resilience architecture |
| [08 - Database Design](docs/architecture/08-database-design.md) | Entity relationships, all table definitions (servers, users, libraries, items, user_data, downloads, media_streams, sync_queue, thumbnails, playlists), key queries, data flow diagrams, storage estimates |
| [09 - Security](docs/architecture/09-security.md) | Authentication token storage, secure storage module, network security, local data protection |

---

## File Structure Summary

```
src-tauri/src/
├── lib.rs                    # Tauri app setup, state initialization
├── commands/                 # Tauri command handlers (90+ commands)
│   ├── mod.rs               # Command exports
│   ├── player.rs            # 16 player commands
│   ├── repository.rs        # 27 repository commands
│   ├── playlist.rs          # 7 playlist commands
│   ├── playback_mode.rs     # 5 playback mode commands
│   ├── connectivity.rs      # 7 connectivity commands
│   ├── storage.rs           # Storage & database commands
│   ├── download.rs          # 7 download commands
│   ├── offline.rs           # 3 offline commands
│   └── sync.rs              # Sync queue commands
├── repository/              # Repository pattern implementation
│   ├── mod.rs               # MediaRepository trait, handle management
│   ├── types.rs             # RepoError, Library, MediaItem, etc.
│   ├── hybrid.rs            # HybridRepository with cache-first racing
│   ├── online.rs            # OnlineRepository (HTTP API)
│   └── offline.rs           # OfflineRepository (SQLite queries)
├── playback_mode/           # Playback mode manager
│   └── mod.rs               # PlaybackMode enum, transfer logic
├── connectivity/            # Connectivity monitoring
│   └── mod.rs               # ConnectivityMonitor, adaptive polling
├── jellyfin/                # Jellyfin API client
│   ├── mod.rs               # Module exports
│   ├── http_client.rs       # HTTP client with retry logic
│   └── client.rs            # JellyfinClient for API calls
├── storage/                 # Database layer
│   ├── mod.rs               # Database struct, migrations
│   ├── db_service.rs        # DatabaseService trait (async wrapper)
│   ├── schema.rs            # Table definitions
│   └── queries/             # Query modules
├── download/                # Download manager module
│   ├── mod.rs               # DownloadManager, DownloadInfo, DownloadTask
│   ├── worker.rs            # DownloadWorker, HTTP streaming, retry logic
│   ├── events.rs            # DownloadEvent enum
│   └── cache.rs             # SmartCache, CacheConfig, LRU eviction
└── player/                  # Player subsystem
    ├── mod.rs               # PlayerController
    ├── session.rs           # MediaSessionManager, MediaSessionType
    ├── state.rs             # PlayerState, PlayerEvent
    ├── media.rs             # MediaItem, MediaSource, MediaType
    ├── queue.rs             # QueueManager, RepeatMode
    ├── backend.rs           # PlayerBackend trait, NullBackend
    ├── events.rs            # PlayerStatusEvent, TauriEventEmitter
    ├── mpv/                 # Linux MPV backend
    │   ├── mod.rs           # MpvBackend implementation
    │   └── event_loop.rs    # Dedicated thread for MPV operations
    └── android/             # Android ExoPlayer backend
        └── mod.rs           # ExoPlayerBackend + JNI bindings

src/lib/
├── api/                     # Thin API layer (~200 lines total)
│   ├── types.ts             # TypeScript type definitions
│   ├── repository-client.ts # RepositoryClient wrapper (~100 lines)
│   ├── client.ts            # JellyfinClient (helper for streaming)
│   └── sessions.ts          # SessionsApi (remote session control)
├── services/
│   ├── playerEvents.ts      # Tauri event listener for player events
│   └── playbackReporting.ts # Thin wrapper (~50 lines)
├── stores/                  # Thin reactive wrappers over Rust commands
│   ├── index.ts             # Re-exports
│   ├── auth.ts              # Auth store (calls Rust commands)
│   ├── player.ts            # Player store
│   ├── queue.ts             # Queue store
│   ├── library.ts           # Library store
│   ├── playbackMode.ts      # Playback mode store (~150 lines)
│   ├── connectivity.ts      # Connectivity store (~250 lines)
│   └── downloads.ts         # Downloads store with event listeners
└── components/
    ├── Search.svelte
    ├── player/              # Player UI components
    ├── playlist/            # Playlist modals (Create, AddTo)
    ├── sessions/            # Remote session control UI
    ├── downloads/           # Download UI components
    └── library/             # Library UI components + PlaylistDetailView
```

## Key Architecture Changes

**What moved to Rust (~3,500 lines of business logic):**
1. **HTTP Client** (338 lines) - Retry logic with exponential backoff
2. **Connectivity Monitor** (301 lines) - Adaptive polling, event emission
3. **Repository Pattern** (1061 lines) - Cache-first hybrid with parallel racing
4. **Database Service** - Async wrapper preventing UI freezing
5. **Playback Mode** (303 lines) - Local/remote transfer coordination

**TypeScript Layer (now ~800 lines, down from ~3,300):**
- Svelte stores (reactive wrappers)
- Type definitions
- UI event handling
- Tauri command invocation
- Event listeners for Rust events

**Total Commands:** 90+ Tauri commands across 14 command modules