allstarr/ARCHITECTURE.md

Architecture

This document describes the technical architecture of Allstarr.

System Architecture

                                                    ┌─────────────────┐
                                               ┌───▶│    Jellyfin     │
┌─────────────────┐     ┌──────────────────┐   │    │    Server       │
│  Music Client   │────▶│     Allstarr     │───┤    └─────────────────┘
│  (Aonsoku,      │◀────│   (Proxy)        │◀──┤
│   Finamp, etc.) │     │                  │   │    ┌─────────────────┐
└─────────────────┘     └────────┬─────────┘   └───▶│   Navidrome     │
                                 │                  │   (Subsonic)    │
                                 ▼                  └─────────────────┘
                        ┌─────────────────┐
                        │ Music Providers │
                        │  - SquidWTF     │
                        │  - Deezer       │
                        │  - Qobuz        │
                        └─────────────────┘

The proxy intercepts requests from your music client and:

1. Forwards library requests to your configured backend (Jellyfin or Subsonic)
2. Merges results with content from your music provider
3. Downloads and caches external tracks on-demand
4. Serves audio streams transparently

Note: Only the controller matching your configured BACKEND_TYPE is registered at runtime, preventing route conflicts and ensuring clean API separation.

API Endpoints

Jellyfin Backend (Primary Focus)

The proxy provides comprehensive Jellyfin API support with streaming provider integration:

Endpoint	Description
GET /Items	Search and browse library items (local + streaming providers)
GET /Artists	Browse artists with merged results from local + streaming
GET /Artists/AlbumArtists	Album artists with streaming provider results
GET /Users/{userId}/Items	User library items with external content
GET /Audio/{id}/stream	Stream audio, downloading from provider on-demand
GET /Audio/{id}/Lyrics	Lyrics from Jellyfin, Spotify, or LRCLib
GET /Items/{id}/Images/{type}	Proxy cover art for external content
GET /Playlists/{id}/Items	Playlist items (Spotify Import integration)
POST /UserFavoriteItems/{id}	Favorite items; copies external tracks to kept folder
DELETE /UserFavoriteItems/{id}	Unfavorite items
POST /Sessions/Playing	Playback reporting for external tracks
POST /Sessions/Playing/Progress	Playback progress tracking
POST /Sessions/Playing/Stopped	Playback stopped reporting
WebSocket /socket	Real-time session management and remote control

Admin API (Port 5275):

Endpoint	Description
GET /api/admin/health	Health check endpoint
GET /api/admin/config	Get current configuration
POST /api/admin/config	Update configuration
POST /api/admin/cache/clear	Clear cache
GET /api/admin/status	Get system status
GET /api/admin/memory-stats	Get memory usage statistics
POST /api/admin/force-gc	Force garbage collection
GET /api/admin/sessions	Get active sessions
GET /api/admin/debug/endpoint-usage	Get endpoint usage statistics
DELETE /api/admin/debug/endpoint-usage	Clear endpoint usage log
GET /api/admin/squidwtf-base-url	Get SquidWTF base URL
GET /api/admin/playlists	List all playlists with status
GET /api/admin/playlists/{name}/tracks	Get tracks for playlist
POST /api/admin/playlists/refresh	Refresh all playlists
POST /api/admin/playlists/{name}/match	Match tracks for playlist
POST /api/admin/playlists/{name}/clear-cache	Clear playlist cache
POST /api/admin/playlists/match-all	Match all playlists
POST /api/admin/playlists	Add new playlist
DELETE /api/admin/playlists/{name}	Remove playlist
POST /api/admin/playlists/{name}/map	Save manual track mapping
GET /api/admin/jellyfin/search	Search Jellyfin library
GET /api/admin/jellyfin/track/{id}	Get Jellyfin track details
GET /api/admin/jellyfin/users	List Jellyfin users
GET /api/admin/jellyfin/libraries	List Jellyfin libraries
GET /api/admin/jellyfin/playlists	List Jellyfin playlists
POST /api/admin/jellyfin/playlists/{id}/link	Link Jellyfin playlist to Spotify
DELETE /api/admin/jellyfin/playlists/{name}/unlink	Unlink playlist
PUT /api/admin/playlists/{name}/schedule	Update playlist sync schedule
GET /api/admin/spotify/user-playlists	Get Spotify user playlists
GET /api/admin/spotify/sync	Trigger Spotify sync
GET /api/admin/spotify/match	Trigger Spotify track matching
POST /api/admin/spotify/clear-cache	Clear Spotify cache
GET /api/admin/spotify/mappings	Get Spotify track mappings (paginated)
GET /api/admin/spotify/mappings/{spotifyId}	Get specific Spotify mapping
POST /api/admin/spotify/mappings	Save Spotify track mapping
DELETE /api/admin/spotify/mappings/{spotifyId}	Delete Spotify mapping
GET /api/admin/spotify/mappings/stats	Get Spotify mapping statistics
GET /api/admin/downloads	List kept downloads
DELETE /api/admin/downloads	Delete kept file
GET /api/admin/downloads/file	Download specific file
GET /api/admin/downloads/all	Download all files as zip
GET /api/admin/scrobbling/status	Get scrobbling status
POST /api/admin/scrobbling/lastfm/authenticate	Authenticate Last.fm
GET /api/admin/scrobbling/lastfm/auth-url	Get Last.fm auth URL
POST /api/admin/scrobbling/lastfm/get-session	Get Last.fm session key
POST /api/admin/scrobbling/lastfm/test	Test Last.fm connection
POST /api/admin/scrobbling/lastfm/debug-auth	Debug Last.fm auth
POST /api/admin/scrobbling/listenbrainz/validate	Validate ListenBrainz token
POST /api/admin/scrobbling/listenbrainz/test	Test ListenBrainz connection

All other Jellyfin API endpoints are passed through unchanged.

Subsonic Backend

The proxy implements the Subsonic API with streaming provider integration:

Endpoint	Description
GET /rest/search3	Merged search results from Navidrome + streaming provider
GET /rest/stream	Streams audio, downloading from provider if needed
GET /rest/getSong	Returns song details (local or from provider)
GET /rest/getAlbum	Returns album with tracks from both sources
GET /rest/getArtist	Returns artist with albums from both sources
GET /rest/getCoverArt	Proxies cover art for external content
GET /rest/star	Stars items; triggers automatic playlist download for external playlists

All other Subsonic API endpoints are passed through to Navidrome unchanged.

External ID Format

External (streaming provider) content uses typed IDs:

Type	Format	Example
Song	ext-{provider}-song-{id}	ext-deezer-song-123456, ext-qobuz-song-789012
Album	ext-{provider}-album-{id}	ext-deezer-album-789012, ext-qobuz-album-456789
Artist	ext-{provider}-artist-{id}	ext-deezer-artist-259, ext-qobuz-artist-123

Legacy format ext-deezer-{id} is also supported (assumes song type).

Download Folder Structure

All downloads are organized under a single base directory (default: ./downloads):

downloads/
├── permanent/                    # Permanent downloads (STORAGE_MODE=Permanent)
│   ├── Artist Name/
│   │   ├── Album Title/
│   │   │   ├── 01 - Track One.flac
│   │   │   ├── 02 - Track Two.flac
│   │   │   └── ...
│   │   └── Another Album/
│   │       └── ...
│   └── playlists/
│       ├── My Favorite Songs.m3u
│       └── Chill Vibes.m3u
├── cache/                        # Temporary cache (STORAGE_MODE=Cache)
│   └── Artist Name/
│       └── Album Title/
│           └── Track.flac
└── kept/                         # Favorited external tracks (always permanent)
    └── Artist Name/
        └── Album Title/
            └── Track.flac

Storage modes:

• Permanent (downloads/permanent/): Files saved permanently and registered in your media server
• Cache (downloads/cache/): Temporary files, auto-cleaned after CACHE_DURATION_HOURS
• Kept (downloads/kept/): External tracks you've favorited - always permanent, separate from cache

Playlists are stored as M3U files with relative paths, making them portable and compatible with most music players.

Metadata Embedding

Downloaded files include:

• Basic: Title, Artist, Album, Album Artist
• Track Info: Track Number, Total Tracks, Disc Number
• Dates: Year, Release Date
• Audio: BPM, Duration
• Identifiers: ISRC (in comments)
• Credits: Contributors/Composers
• Visual: Embedded cover art (high resolution)
• Rights: Copyright, Label