201 lines
10 KiB
Markdown
201 lines
10 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-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
|