10 KiB
10 KiB
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
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/:
| Document | Contents |
|---|---|
| 01 - Rust Backend | 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 | 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 | Repository query flow (cache-first), playback initiation, playback mode transfer, queue navigation, volume control |
| 04 - Type Sync & Threading | Rust/TypeScript type synchronization, Tauri v2 IPC parameter naming convention, thread safety patterns |
| 05 - Platform Backends | Player events system, MpvBackend (Linux), ExoPlayerBackend (Android), MediaSession & remote volume, album art caching, backend initialization |
| 06 - Downloads & Offline | Download manager, download worker, smart caching engine, download/offline commands, player integration, frontend store, UI components |
| 07 - Connectivity | HTTP client with retry logic, connectivity monitor, network resilience architecture |
| 08 - Database Design | 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 | 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):
- HTTP Client (338 lines) - Retry logic with exponential backoff
- Connectivity Monitor (301 lines) - Adaptive polling, event emission
- Repository Pattern (1061 lines) - Cache-first hybrid with parallel racing
- Database Service - Async wrapper preventing UI freezing
- 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