[Architecture] Offline-first proxy for online mode to improve low-bandwidth experience

[test3207]

Problem

In online mode with slow network connections, the user experience degrades significantly. Currently, online mode fetches all data directly from the backend API, which leads to:

• Slow page loads and audio buffering on poor connections
• Stuttering playback when network fluctuates
• Poor perceived performance compared to offline/guest mode

Parent Issue: Epic 4.1: Feature Enhancements (#142)

Proposed Solution

Adopt an offline-first architecture for online mode as well:

1. Local-first data access: All reads (libraries, playlists, songs, audio streams) should go through the IndexedDB proxy first
2. Background sync: Backend API only handles data synchronization in the background
3. Progressive enhancement:
   • Immediately show cached data
   • Fetch updates from backend asynchronously
   • Sync user mutations when network is available

Architecture Changes

Current (Online Mode):
Browser → Backend API → PostgreSQL/MinIO

Proposed (Unified Offline-First):
Browser → IndexedDB Proxy → Cache Storage (audio)
                ↓ (background sync)
           Backend API → PostgreSQL/MinIO

Benefits

• Instant page loads with cached data
• Smooth playback even on unstable connections
• Consistent UX between online and offline modes
• Reduced server load (fewer redundant requests)
• Natural conflict resolution via sync queue

Considerations

• Sync conflict resolution strategy needed
• Storage quota management for cached content
• Initial sync flow for new devices
• Selective sync (user chooses what to cache)

Related

• Current offline proxy implementation: frontend/src/services/offline-proxy.ts
• Guest mode already uses this pattern successfully
• Issue Migrate audio/cover storage from IndexedDB to Cache Storage API #49 (PWA Integration) established the foundation
• Epic 2.4 (Epic 2.4: Unified Offline Sync Architecture #131) Unified Offline Sync Architecture (completed)

Acceptance Criteria

• Architecture design document approved
• Online mode reads from local cache first
• Background sync keeps local and remote in sync
• Playback resilient to network fluctuations