# acousticufo/jellyfin-audio-provider architecture

> Architecture diagram of the GitHub repository acousticufo/jellyfin-audio-provider, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/acousticufo/jellyfin-audio-provider
- Repository: https://github.com/acousticufo/jellyfin-audio-provider

## Overview

Jellyfin Audio Provider exposes a Jellyfin music library as a native Android Storage Access Framework tree for local media players. The main flow is a player browsing provider documents, with metadata served from the local index and audio delivered by range streaming; a separate foreground sync populates that index. The graph also captures the connection, cache-management, and setup-guide UI, plus security boundaries. Some subsystem links are based on the SOURCE INDEX or README rather than complete call-site excerpts; those evidence limits are reflected in the cited paths.

Main entry points: [`app/src/main/java/com/github/jellyfin_saf/api/JellyfinClient.kt`](https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/api/JellyfinClient.kt) (Jellyfin API client), [`app/src/main/java/com/github/jellyfin_saf/ui/MainActivity.kt`](https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/ui/MainActivity.kt) (Compose navigation), [`app/src/main/java/com/github/jellyfin_saf/provider/JellyfinDocumentsProvider.kt`](https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/provider/JellyfinDocumentsProvider.kt) (Documents provider), [`app/src/main/java/com/github/jellyfin_saf/sync/LibrarySyncService.kt`](https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/sync/LibrarySyncService.kt) (Foreground sync)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["App interface"]
  node_main["Compose navigation<br/>[MainActivity.kt]"]
  node_connection["Connection screen"]
  node_cache_screen["Cache screen<br/>[CacheScreen.kt]"]
  node_guide["Setup guide<br/>[HelpScreen.kt]"]
end

subgraph group_provider["SAF documents"]
  node_documents["Documents provider"]
  node_document_ids["Document identifiers<br/>[DocumentId.kt]"]
end

subgraph group_library["Library sync and index"]
  node_sync_service["Foreground sync"]
  node_sync_state["Sync state"]
  node_api["Jellyfin API client<br/>[JellyfinClient.kt]"]
  node_models["Jellyfin metadata models<br/>[JellyfinModels.kt]"]
  node_database[("Room database<br/>[AppDatabase.kt]")]
  node_dao["Track queries<br/>[TrackDao.kt]"]
  node_track["Track metadata<br/>[TrackEntity.kt]"]
end

subgraph group_streaming["Streaming and cache"]
  node_proxy["Range stream proxy"]
  node_stream_service["Playback foreground service"]
  node_intervals["Fetched byte ranges<br/>[IntervalSet.kt]"]
  node_cache[("LRU disk cache<br/>[LRUCacheManager.kt]")]
end

subgraph group_security["Security"]
  node_validator["Input and path validation<br/>[InputValidator.kt]"]
  node_preferences[("Encrypted preferences")]
end

node_user(("App user"))
node_player(("SAF media player"))
node_android["Android SAF"]
node_jellyfin["Jellyfin server"]

node_user -->|"configures"| node_main
node_main -->|"shows"| node_connection
node_main -->|"shows"| node_cache_screen
node_main -->|"shows"| node_guide
node_main -->|"provides"| node_api
node_main -->|"provides"| node_cache
node_connection -->|"uses"| node_api
node_connection -->|"starts"| node_sync_service
node_connection -->|"observes"| node_sync_state
node_cache_screen -->|"manages"| node_cache
node_cache_screen -->|"reads settings"| node_preferences
node_player -->|"opens provider"| node_android
node_android -->|"dispatches"| node_documents
node_documents -->|"uses identifiers"| node_document_ids
node_documents -->|"queries metadata"| node_api
node_documents -->|"reads index"| node_database
node_documents -->|"builds records"| node_track
node_documents -->|"opens audio"| node_proxy
node_sync_service -->|"fetches library"| node_api
node_sync_service -->|"stores index"| node_database
node_sync_service -->|"creates records"| node_track
node_sync_service -->|"updates cache"| node_cache
node_sync_service -->|"publishes progress"| node_sync_state
node_api -->|"requests metadata"| node_jellyfin
node_api -->|"uses credentials"| node_preferences
node_api -->|"decodes responses"| node_models
node_database -->|"exposes queries"| node_dao
node_dao -->|"queries records"| node_track
node_proxy -->|"requests byte ranges"| node_jellyfin
node_proxy -->|"reads and writes"| node_cache
node_proxy -->|"tracks fetched ranges"| node_intervals
node_proxy -.->|"uses service"| node_stream_service
node_cache -->|"updates cache status"| node_database
node_cache -->|"validates paths"| node_validator
node_document_ids -->|"validates identifiers"| node_validator
node_preferences -.->|"encrypts with Keystore"| node_android

click node_main "https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/ui/MainActivity.kt"
click node_connection "https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/ui/screens/ConnectionScreen.kt"
click node_cache_screen "https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/ui/screens/CacheScreen.kt"
click node_guide "https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/ui/screens/HelpScreen.kt"
click node_documents "https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/provider/JellyfinDocumentsProvider.kt"
click node_document_ids "https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/provider/DocumentId.kt"
click node_sync_service "https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/sync/LibrarySyncService.kt"
click node_sync_state "https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/sync/LibrarySyncManager.kt"
click node_api "https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/api/JellyfinClient.kt"
click node_models "https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/api/model/JellyfinModels.kt"
click node_database "https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/db/AppDatabase.kt"
click node_dao "https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/db/TrackDao.kt"
click node_track "https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/db/TrackEntity.kt"
click node_proxy "https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/stream/ProxyStreamHandler.kt"
click node_stream_service "https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/stream/StreamingService.kt"
click node_intervals "https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/stream/IntervalSet.kt"
click node_cache "https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/cache/LRUCacheManager.kt"
click node_validator "https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/security/InputValidator.kt"
click node_preferences "https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/security/SecurePreferences.kt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_connection,node_cache_screen,node_guide,node_user toneBlue
class node_documents,node_document_ids toneAmber
class node_sync_service,node_sync_state,node_api,node_models,node_database,node_dao,node_track,node_jellyfin toneMint
class node_proxy,node_stream_service,node_intervals,node_cache toneRose
class node_validator,node_preferences,node_player,node_android toneIndigo
```

## Components

### App interface

- [Compose navigation](https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/ui/MainActivity.kt): `app/src/main/java/com/github/jellyfin_saf/ui/MainActivity.kt`
- [Connection screen](https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/ui/screens/ConnectionScreen.kt): `app/src/main/java/com/github/jellyfin_saf/ui/screens/ConnectionScreen.kt`
- [Cache screen](https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/ui/screens/CacheScreen.kt): `app/src/main/java/com/github/jellyfin_saf/ui/screens/CacheScreen.kt`
- [Setup guide](https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/ui/screens/HelpScreen.kt): `app/src/main/java/com/github/jellyfin_saf/ui/screens/HelpScreen.kt`

### SAF documents

- [Documents provider](https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/provider/JellyfinDocumentsProvider.kt): `app/src/main/java/com/github/jellyfin_saf/provider/JellyfinDocumentsProvider.kt`
- [Document identifiers](https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/provider/DocumentId.kt): `app/src/main/java/com/github/jellyfin_saf/provider/DocumentId.kt`

### Library sync and index

- [Foreground sync](https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/sync/LibrarySyncService.kt): `app/src/main/java/com/github/jellyfin_saf/sync/LibrarySyncService.kt`
- [Sync state](https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/sync/LibrarySyncManager.kt): `app/src/main/java/com/github/jellyfin_saf/sync/LibrarySyncManager.kt`
- [Jellyfin API client](https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/api/JellyfinClient.kt): `app/src/main/java/com/github/jellyfin_saf/api/JellyfinClient.kt`
- [Jellyfin metadata models](https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/api/model/JellyfinModels.kt): `app/src/main/java/com/github/jellyfin_saf/api/model/JellyfinModels.kt`
- [Room database](https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/db/AppDatabase.kt): `app/src/main/java/com/github/jellyfin_saf/db/AppDatabase.kt`
- [Track queries](https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/db/TrackDao.kt): `app/src/main/java/com/github/jellyfin_saf/db/TrackDao.kt`
- [Track metadata](https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/db/TrackEntity.kt): `app/src/main/java/com/github/jellyfin_saf/db/TrackEntity.kt`

### Streaming and cache

- [Range stream proxy](https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/stream/ProxyStreamHandler.kt): `app/src/main/java/com/github/jellyfin_saf/stream/ProxyStreamHandler.kt`
- [Playback foreground service](https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/stream/StreamingService.kt): `app/src/main/java/com/github/jellyfin_saf/stream/StreamingService.kt`
- [Fetched byte ranges](https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/stream/IntervalSet.kt): `app/src/main/java/com/github/jellyfin_saf/stream/IntervalSet.kt`
- [LRU disk cache](https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/cache/LRUCacheManager.kt): `app/src/main/java/com/github/jellyfin_saf/cache/LRUCacheManager.kt`

### Security

- [Input and path validation](https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/security/InputValidator.kt): `app/src/main/java/com/github/jellyfin_saf/security/InputValidator.kt`
- [Encrypted preferences](https://github.com/acousticufo/jellyfin-audio-provider/blob/main/app/src/main/java/com/github/jellyfin_saf/security/SecurePreferences.kt): `app/src/main/java/com/github/jellyfin_saf/security/SecurePreferences.kt`

### Other components

- **App user**
- **SAF media player**
- **Android SAF**
- **Jellyfin server**

## Connections

- App user → Compose navigation: configures (evidence: `app/src/main/java/com/github/jellyfin_saf/ui/MainActivity.kt`)
- Compose navigation → Connection screen: shows (evidence: `app/src/main/java/com/github/jellyfin_saf/ui/MainActivity.kt`)
- Compose navigation → Cache screen: shows (evidence: `app/src/main/java/com/github/jellyfin_saf/ui/MainActivity.kt`)
- Compose navigation → Setup guide: shows (evidence: `app/src/main/java/com/github/jellyfin_saf/ui/MainActivity.kt`)
- Compose navigation → Jellyfin API client: provides (evidence: `app/src/main/java/com/github/jellyfin_saf/ui/MainActivity.kt`)
- Compose navigation → LRU disk cache: provides (evidence: `app/src/main/java/com/github/jellyfin_saf/ui/MainActivity.kt`)
- Connection screen → Jellyfin API client: uses (evidence: `app/src/main/java/com/github/jellyfin_saf/ui/screens/ConnectionScreen.kt`)
- Connection screen → Foreground sync: starts (evidence: `app/src/main/java/com/github/jellyfin_saf/ui/screens/ConnectionScreen.kt`)
- Connection screen → Sync state: observes (evidence: `app/src/main/java/com/github/jellyfin_saf/ui/screens/ConnectionScreen.kt`)
- Cache screen → LRU disk cache: manages (evidence: `app/src/main/java/com/github/jellyfin_saf/ui/screens/CacheScreen.kt`)
- Cache screen → Encrypted preferences: reads settings (evidence: `app/src/main/java/com/github/jellyfin_saf/ui/screens/CacheScreen.kt`)
- SAF media player → Android SAF: opens provider (evidence: `README.md`)
- Android SAF → Documents provider: dispatches (evidence: `README.md`)
- Documents provider → Document identifiers: uses identifiers (evidence: `app/src/main/java/com/github/jellyfin_saf/provider/JellyfinDocumentsProvider.kt`)
- Documents provider → Jellyfin API client: queries metadata (evidence: `app/src/main/java/com/github/jellyfin_saf/provider/JellyfinDocumentsProvider.kt`)
- Documents provider → Room database: reads index (evidence: `app/src/main/java/com/github/jellyfin_saf/provider/JellyfinDocumentsProvider.kt`)
- Documents provider → Track metadata: builds records (evidence: `app/src/main/java/com/github/jellyfin_saf/provider/JellyfinDocumentsProvider.kt`)
- Documents provider → Range stream proxy: opens audio (evidence: `app/src/main/java/com/github/jellyfin_saf/provider/JellyfinDocumentsProvider.kt`)
- Foreground sync → Jellyfin API client: fetches library (evidence: `app/src/main/java/com/github/jellyfin_saf/sync/LibrarySyncService.kt`)
- Foreground sync → Room database: stores index (evidence: `app/src/main/java/com/github/jellyfin_saf/sync/LibrarySyncService.kt`)
- Foreground sync → Track metadata: creates records (evidence: `app/src/main/java/com/github/jellyfin_saf/sync/LibrarySyncService.kt`)
- Foreground sync → LRU disk cache: updates cache (evidence: `app/src/main/java/com/github/jellyfin_saf/sync/LibrarySyncService.kt`)
- Foreground sync → Sync state: publishes progress (evidence: `app/src/main/java/com/github/jellyfin_saf/sync/LibrarySyncService.kt`)
- Jellyfin API client → Jellyfin server: requests metadata (evidence: `README.md`)
- Jellyfin API client → Encrypted preferences: uses credentials (evidence: `app/src/main/java/com/github/jellyfin_saf/api/JellyfinClient.kt`)
- Jellyfin API client → Jellyfin metadata models: decodes responses (evidence: `app/src/main/java/com/github/jellyfin_saf/api/JellyfinClient.kt`)
- Room database → Track queries: exposes queries (evidence: `app/src/main/java/com/github/jellyfin_saf/db/AppDatabase.kt`)
- Track queries → Track metadata: queries records (evidence: `app/src/main/java/com/github/jellyfin_saf/db/TrackDao.kt`)
- Range stream proxy → Jellyfin server: requests byte ranges (evidence: `README.md`)
- Range stream proxy → LRU disk cache: reads and writes (evidence: `app/src/main/java/com/github/jellyfin_saf/stream/ProxyStreamHandler.kt`)
- Range stream proxy → Fetched byte ranges: tracks fetched ranges (evidence: `app/src/main/java/com/github/jellyfin_saf/stream/ProxyStreamHandler.kt`)
- Range stream proxy → Playback foreground service: uses service (evidence: `app/src/main/java/com/github/jellyfin_saf/stream/ProxyStreamHandler.kt`)
- LRU disk cache → Room database: updates cache status (evidence: `app/src/main/java/com/github/jellyfin_saf/cache/LRUCacheManager.kt`)
- LRU disk cache → Input and path validation: validates paths (evidence: `app/src/main/java/com/github/jellyfin_saf/cache/LRUCacheManager.kt`)
- Document identifiers → Input and path validation: validates identifiers (evidence: `app/src/main/java/com/github/jellyfin_saf/provider/DocumentId.kt`)
- Encrypted preferences → Android SAF: encrypts with Keystore
