Llamafin Architecture & Technology
Audience: End users and technical evaluators Last Updated: 2026-04-04 Version: 2.0.0
Overview
Llamafin is a cross-platform media player application built with modern web technologies. It connects to your Jellyfin media server to deliver a rich, feature-complete music listening experience across mobile, desktop, and web platforms.
Technology Foundation
Built With Industry-Standard Frameworks
Llamafin leverages battle-tested technologies to ensure reliability, performance, and maintainability:
| Component | Technology | Why It Matters |
|---|---|---|
| Application Framework | Angular 16 | Enterprise-grade framework with strong typing and component-based architecture |
| User Interface | Ionic 7 | Native-quality UI components that work consistently across all platforms |
| Mobile Platform | Capacitor 5 | Direct access to native device features (camera, filesystem, haptics) |
| Desktop Platform | Electron 25 | Full desktop application with system tray integration and native menus |
| State Management | NgRx 16 | Predictable state management ensuring UI consistency and debuggability |
| Audio Streaming | HLS.js + Web Audio API | Adaptive bitrate streaming with professional audio processing capabilities |
| Visualisation | Butterchurn | Industry-standard MilkDrop-compatible audio Visualisations |
Application Architecture
Three-Tier Architecture
Llamafin follows a clean separation of concerns across three layers:
┌─────────────────────────────────────────┐
│ Presentation Layer │
│ User Interface & User Interaction │
└─────────────────────────────────────────┘
↓
┌─────────────────────────────────────────┐
│ Business Logic Layer │
│ State Management & Feature Services │
└─────────────────────────────────────────┘
↓
┌─────────────────────────────────────────┐
│ Infrastructure Layer │
│ Networking, Storage & Device Access │
└─────────────────────────────────────────┘
1. Presentation Layer
The presentation layer handles everything you see and interact with:
- Component-Based Design: Every UI element is a self-contained component
- Change Detection: Optimised rendering only updates what's necessary
- Responsive Layouts: Adapts seamlessly to phone, tablet, and desktop screens
- Theme System: Light, dark, black, and white themes with customizable backgrounds
2. Business Logic Layer
The intelligence behind the application:
- Feature Modules: 33 independent feature modules, each managing a specific capability
- State Management: 45+ state slices tracking everything from playback to settings
- Reactive Programming: UI automatically updates in response to state changes
- Unidirectional Data Flow: All data flows in one direction, preventing bugs and making the app predictable
3. Infrastructure Layer
The foundation that powers everything:
- HTTP Communication: Six-layer interceptor pipeline for robust API communication
- Offline Storage: IndexedDB-based storage for downloads and app data
- Device Integration: Native device features through Capacitor plugins
- WebSocket Connection: Real-time event subscription with your Jellyfin server
Platform Support
Mobile Platforms
iOS & Android (via Capacitor 5):
- Native file system access for offline downloads
- Haptic feedback for tactile interactions
- Media Session API integration (car UI, lock screen controls)
- Background audio playback
- Network awareness (WiFi vs cellular optimisation)
Desktop Platforms
Windows, macOS, Linux (via Electron 25):
| Platform | Architecture | Package Format |
|---|---|---|
| Windows | ia32, x64 | Installer (.exe), Portable |
| macOS | x64 | Installer (.dmg), Application bundle |
| Linux | x64 | Debian (.deb), AppImage, Generic |
Desktop Features:
- System tray integration
- Global media key support
- Native file dialogues
- Custom title bars
- Window state persistence
- Service Worker for caching and offline capability
- Web app manifest for installability
- Push notification support
- Browser-based HLS streaming
Feature Architecture
33 Feature Modules
Llamafin's functionality is organised into independent feature modules:
Core Features
| Feature | Purpose |
|---|---|
| Authentication | Secure login with Jellyfin, Quick Connect support, session management |
| Audio Engine | Professional audio processing with 10-band EQ, stereo control, loudness compensation |
| Player | Queue management, shuffle/repeat modes, autoplay, preview playback |
| Library | Browse and manage your music collection (albums, artists, songs, genres, playlists) |
| Search | Find content with online and offline search, suggestions |
| Settings | 10 categories of customizable preferences |
Advanced Features
| Feature | Purpose |
|---|---|
| DJ Mode | Automatic queue generation with smart play modes |
| Sonic Analysis | Audio fingerprinting to find sonically similar tracks |
| Llamafin Connect | Peer-to-peer device control with cryptographic security |
| Remote Control | Synchronised playback across multiple devices |
| Downloads | Offline playback with chunked downloads and transcoding |
| Device Metrics | Real-time and historical performance monitoring |
UI/UX Features
| Feature | Purpose |
|---|---|
| Visualisations | Butterchurn (MilkDrop) and spectrum analyser visualizers |
| Lyrics | Display synchronised lyrics with remote search |
| Sleep Timer | Automatic playback shutdown |
| Themes | Light, dark, black, and white themes with custom backgrounds |
| Internationalization | Multi-language support with dynamic switching |
State Management
Predictable State with NgRx
Llamafin uses NgRx (Redux for Angular) to manage application state:
How It Works:
- User Action: You interact with the UI (e.g., click "Play")
- Action Dispatched: A typed action object is sent to the store
- Effects Handle Side Effects: API calls, navigation, etc.
- Reducer Updates State: Pure function creates new state
- Selectors Provide Data: Memoized selectors extract needed data
- UI Updates Automatically: Components react to state changes
Why This Matters:
- Predictability: Same actions always produce same state changes
- Debuggability: Every state change is traceable and logged
- Performance: Memoized selectors prevent unnecessary recalculations
- Consistency: Single source of truth eliminates state conflicts
45+ State Slices
Each major feature has its own isolated state slice:
| State Slice | Tracks |
|---|---|
auth | Login status, user info, session token |
player | Queue, current track, shuffle/repeat mode |
audio | Playback state, volume, EQ settings |
library | Active library, user views |
settings | All user preferences (composite) |
downloads | Download status, metadata, file paths |
network | Connectivity, server status, speed |
websocket | Real-time connection status |
Security Architecture
Authentication Flow
- Login: Username and password sent to Jellyfin server
- Token Storage: Authentication token stored securely with expiry
- Session Rehydration: On app start, token validated and session restored
- User Hashing: SHA-256 hash of User ID computed for P2P pairing
- Auto-Logout: Invalid tokens trigger secure logout
Data Protection
- Password Hashing: Passwords never stored locally, only server-authenticated
- Token Expiry: Authentication tokens have expiration dates
- Secure P2P: Cryptographic key pairs for device identity
- HTTPS Support: All communication can be encrypted in transit
HTTP Security
Six-layer interceptor pipeline:
- Server URL Injection: Routes requests to correct server
- Error Handling: Global error management
- Authentication: Automatic token injection
- Retry Logic: Automatic retry on transient failures
- Cache Prevention: Timestamps prevent stale data
- Unauthorized Handling: 401 responses trigger secure logout
Offline Architecture
Download System
Llamafin's offline capability is powered by a sophisticated download system:
Download Types:
- Direct Downloads: Original file format
- Transcoded Downloads: Server-side conversion for compatibility
- Chunked Downloads: Parallel chunk downloading for performance
Features:
- Concurrent chunk downloads
- Download resume on interruption
- Smart download detection
- Offline queue management
- Storage path selection (internal/external)
Storage Layer
- IndexedDB: Primary storage for downloads and cached data
- File System API: Native file access for offline media
- Queued Operations: Storage calls queued until database ready
- Version Migration: Database version tracking (v49)
Audio Architecture
Web Audio API Integration
Professional audio processing pipeline:
Audio File → Decoder → EQ (10-band) → Stereo Control → Loudness → Limiter → Analyser → Output
Audio Features:
- 10-Band Equalizer: Precision frequency control
- Stereo Panning: Left/right balance control
- Stereo Width: Haas effect for spatial audio
- Loudness Compensation: Consistent volume across tracks
- Audio Limiter: Prevent distortion at high volumes
- Analyser Node: Real-time frequency data for Visualisations
Streaming Support
- HLS.js: Adaptive bitrate streaming from Jellyfin
- Gapless Playback: Seamless track transitions
- Preview Mode: 30-second previews for browsing
- Buffer Management: Intelligent pre-buffering
Real-Time Communication
WebSocket Integration
Llamafin maintains a real-time connection to your Jellyfin server:
What It Monitors:
- Playback state changes
- Library updates
- User notifications
- System events
Connection Management:
- Automatic reconnection on failure
- Offline operation when disconnected
- Connection status tracking
- Event buffering during outages
Performance Architecture
optimisation Strategies
| Strategy | Implementation |
|---|---|
| Lazy Loading | All pages loaded on-demand |
| Change Detection | OnPush strategy prevents unnecessary checks |
| Memoization | Selectors cache computed results |
| Bundle Limits | 4mb initial bundle warning, 5mb hard limit |
| Component Styles | 16kb per-component style limit |
| Subscription Management | Automatic cleanup prevents memory leaks |
Monitoring & Debugging
Built-In Tools:
- Device metrics tracking (CPU, memory, network)
- Performance overlay (FPS, render time)
- Audio debugging overlay
- Storage inspection tools
- Log viewer with filtering
Development Tools:
- State change logging (dev mode)
- Background state tracking
- Angular DevTools support
- Network speed testing
Internationalization
Multi-Language Support
- Dynamic Language Switching: Change language without restart
- Supported Languages: Multiple languages with translation scripts
- Translation APIs: Google Translate and DeepL integration
- Pluralization: Language-aware plural rules
- Date/Number Formatting: Locale-aware formatting
Extensibility
Plugin & Extension Points
While Llamafin is a closed-source application, the architecture supports:
- Custom Visualizers: Plug-in audio Visualisations
- DJ Modes: Configurable auto-play algorithms
- Sonic Analysis: Extensible audio fingerprinting
- Server Plugins: Jellyfin server-side extensions
Build System
Automated Build Pipeline
Development: npm start # Hot-reload development server
Production: npm run build # Optimised production build
Mobile: npm run build-android / build-ios
Desktop: npm run package-win-x64 / package-mac / package-linux
Version Management
- Semantic Versioning: Major.Minor.Patch (2.0.0)
- Automated Versioning: Scripts for version bumps
- Database Versioning: Tracks IndexedDB schema (v49)
- Environment Swapping: Dev/prod configuration replacement
Dependency Management
Production Dependencies
- 75+ npm packages including Angular, Ionic, Capacitor, NgRx
- 7 custom native libraries (crypto, device metrics, discovery, etc.)
- Audio libraries: HLS.js, Butterchurn, fft.js, mux.js, jsmediatags
- UI libraries: Font Awesome, Chart.js
Code Quality
- TypeScript Strict Mode: Zero tolerance for type errors
- ESLint: Automated code quality checks
- Template Type Checking: Strict template compilation
- Component Suffix Rules: Enforced naming conventions
Architecture Benefits
For Users
✅ Reliability: Predictable state management prevents UI bugs ✅ Performance: Optimised rendering and lazy loading ✅ Offline Capability: Robust download and storage system ✅ Cross-Platform: Consistent experience everywhere ✅ Extensibility: New features can be added safely
For Technical Evaluators
✅ Maintainability: Clean architecture with feature isolation ✅ Testability: Service layer abstraction enables mocking ✅ Scalability: Modular structure supports growth ✅ Type Safety: Strict TypeScript prevents runtime errors ✅ Debuggability: Complete state traceability
Technical Specifications
| Specification | Value |
|---|---|
| Framework | Angular 16.0.0 |
| UI Library | Ionic 7.0.1 |
| State Management | NgRx 16.0.0 |
| Mobile Runtime | Capacitor 5.2.1 |
| Desktop Runtime | Electron 25.3.2 |
| TypeScript | Strict mode enabled |
| Database Version | 49 |
| Feature Modules | 33 |
| State Slices | 45+ |
| Route Definitions | 80+ |
| Shared Components | 50+ |
| HTTP Interceptors | 6 |
| Supported Platforms | iOS, Android, Windows, macOS, Linux |