Duncan Tourolle
1f6977cd01
All checks were successful
🏗️ Build and Test JellyTau / Run Tests (push) Successful in 4m28s
Traceability Validation / Check Requirement Traces (push) Successful in 22s
🏗️ Build and Test JellyTau / Build Android APK (push) Successful in 18m37s
Build & Release / Run Tests (push) Successful in 4m12s
Build & Release / Build Linux (push) Successful in 16m20s
Build & Release / Build Android (push) Successful in 18m57s
Build & Release / Create Release (push) Successful in 13s
211 lines
13 KiB
Markdown
211 lines
13 KiB
Markdown
# 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-06-20
|
|
|
|
## Architecture Overview
|
|
|
|
JellyTau uses a client-server architecture: business logic lives in a comprehensive Rust backend, while a UI-rich Svelte frontend handles presentation and interaction.
|
|
|
|
### Architecture Principles
|
|
|
|
- **Business Logic in Rust**: Core logic — playback, repository, sync, downloads, connectivity — lives in Rust for performance, reliability, and type safety.
|
|
- **Presentation in Svelte**: The frontend (~20.5k non-test lines) owns UI, layout, navigation, and interaction state and invokes Rust commands. It is intentionally UI-heavy, **not** a thin wrapper. Largest pieces: components + routes (~14.6k lines), stores (~3.4k), api/services/utils (~2.4k); `VideoPlayer.svelte` alone is ~1.6k lines.
|
|
- **Events + Polling hybrid**: Rust emits events the frontend listens to, and the UI also polls status on short intervals in a few hot spots (e.g. queue status in `library/+layout.svelte`, playback progress in `VideoPlayer.svelte`).
|
|
- **Unified player boundary**: UI components control playback only through the frontend facade `src/lib/player/index.ts` (`playerController`), never by calling `commands.player*` directly. Webview-rendered HTML5 video reports its state back into Rust via `src/lib/player/html5Adapter.ts` and the `player_report_*` commands, so the `PlayerController` stays the single source of truth in both native (MPV/ExoPlayer) and HTML5 modes (see [05-platform-backends.md](05-platform-backends.md)).
|
|
- **Handle-Based Resources**: UUID handles for stateful Rust objects.
|
|
- **Cache-First**: Parallel queries with intelligent fallback.
|
|
- **Single source of truth for reachability**: Server reachability is derived from the outcome of *real repository traffic*, not a side-channel poller. The `OnlineRepository` reports each server result to the `ConnectivityMonitor` (classified via `RepoError`), which applies a time-window debounce before declaring the server offline and recovers instantly on the first success. The standalone `/System/Info/Public` probe runs *only while offline*, as a recovery detector for idle sessions.
|
|
- **Poison-tolerant locking**: Shared `std::sync` state is accessed via the `MutexSafe`/`RwLockSafe` helpers in `utils/lock.rs`, which recover a poisoned lock instead of cascading a panic across the player.
|
|
- **Graceful backend init**: If a native player backend (MPV/ExoPlayer) fails to initialize, the app falls back to a no-op backend and emits a `backend-init-failed` event rather than crashing.
|
|
|
|
```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
|
|
Repository -->|"reports server outcome<br/>(success / RepoError)"| ConnectivityMonitor
|
|
end
|
|
```
|
|
|
|
> The `Repository --> ConnectivityMonitor` edge is the source of truth for the offline/online banner: every server request the user actually makes updates reachability. The monitor's own polling is now an offline-only recovery probe (see [07-connectivity.md](07-connectivity.md)).
|
|
|
|
---
|
|
|
|
## Detailed Documentation
|
|
|
|
Each major subsystem is documented in its own file in this directory:
|
|
|
|
| Document | Contents |
|
|
|----------|----------|
|
|
| [01 - Rust Backend](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](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](03-data-flow.md) | Repository query flow (cache-first), playback initiation, playback mode transfer, queue navigation, volume control |
|
|
| [04 - Type Sync & Threading](04-type-sync-and-threading.md) | Rust/TypeScript type synchronization, Tauri v2 IPC parameter naming convention, thread safety patterns |
|
|
| [05 - Platform Backends](05-platform-backends.md) | Player events system, MpvBackend (Linux), ExoPlayerBackend (Android), MediaSession & remote volume, album art caching, backend initialization |
|
|
| [06 - Downloads & Offline](06-downloads-and-offline.md) | Download manager, download worker, smart caching engine, download/offline commands, player integration, frontend store, UI components |
|
|
| [07 - Connectivity](07-connectivity.md) | HTTP client with retry logic, connectivity monitor, network resilience architecture |
|
|
| [08 - Database Design](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](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)
|
|
├── player/ # Unified player boundary (frontend)
|
|
│ ├── index.ts # playerController facade — the only write-side entry point for playback
|
|
│ └── html5Adapter.ts # Reports webview <video> DOM events back into Rust (player_report_*)
|
|
├── 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) - Reachability derived from real repository traffic, time-window debounce, offline-only recovery probe, 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
|
|
|
|
**Svelte/TypeScript frontend (~20.5k non-test lines, plus ~9.6k test lines):**
|
|
- Components + routes (~14.6k lines) — UI and presentation
|
|
- Stores (~3.4k lines) — reactive state that invokes Rust commands and listens for events
|
|
- api / services / utils (~2.4k lines) — typed clients, event listeners, conversion helpers
|
|
|
|
The frontend is genuinely UI-heavy; business decisions live in Rust, but the UI owns layout, navigation, and interaction state.
|
|
|
|
**Total Commands:** 90+ Tauri commands across 14 command modules
|