Design playlist syncing for multiple media servers

[timusus]

📋 Overview This PR introduces a comprehensive architecture design document for implementing bidirectional playlist synchronization between Shuttle2 and media servers (Jellyfin, Emby, Plex).

Addresses: #102 - Sync S2 playlist actions with Jellyfin server

🎯 Problem Statement Currently, Shuttle2 supports one-way sync (pull playlists from media servers), but modifications made locally (adding/removing songs, renaming, deleting) don't sync back to the server. This creates:

Divergence between Shuttle2 and server state Manual maintenance burden across multiple clients Confusion when playlists differ between devices ✨ What's Included Complete Architecture Document (PLAYLIST_SYNC_ARCHITECTURE.md) A production-ready design covering:

Core Components

PlaylistSyncProvider interface for server-agnostic sync operations PlaylistSyncCoordinator for managing sync lifecycle SyncQueueRepository with persistent queue and retry logic Repository interceptor pattern for non-invasive change tracking Conflict Resolution Strategy

Safe Auto-Merge (default): Preserves all content when safe User prompts only for destructive conflicts (renames, deletions) Configurable preferences: Auto-merge, Always Local, Always Remote, Ask Me Sync Configuration

Daily background sync (default, battery-friendly) User configurable: 15 min, hourly, 6 hours, daily, or manual only Global enable/disable per server type (Jellyfin/Emby/Plex) Smart playlists excluded (query-based, read-only) Media Server API Analysis

Jellyfin: Full CRUD support (with known bugs documented + workarounds) Emby: Most stable API, excellent documentation Plex: Comprehensive but different paradigm (URI-based) Implementation Roadmap

8 phases over 12 weeks Feature flags for gradual rollout Backward compatible (no breaking changes) Clear success criteria for each phase 🏗️ Architecture Highlights Clean Architecture Principles Presentation → Domain (Sync Coordinator) → Data (Repository + Providers) → Network ✅ SOLID principles throughout ✅ Repository pattern with reactive streams (Flow) ✅ Plugin architecture for media providers ✅ Offline-first with persistent sync queue ✅ Resilient error handling and conflict resolution ✅ Testable with clear component boundaries Key Technical Decisions | Decision | Choice | Rationale | |----------|--------|-----------| | Change Tracking | Repository Interceptor | Non-invasive, decorator pattern | | Sync Queue | Room database | Survives app restarts, queryable | | Conflict Detection | Content hashing | Efficient state comparison | | Background Sync | WorkManager | Battery-aware, constraint-based | | Scope | Global per server | Simple UX, less overhead |

📊 Design Decisions (Resolved) All open questions have been answered:

✅ Conflict Resolution: Safe Auto-Merge (preserve content, minimize prompts) ✅ Sync Frequency: Daily default (user configurable) ✅ Sync Scope: Global per server type (Jellyfin/Emby/Plex toggles) ✅ Smart Playlists: No sync (query-based, read-only) 🚀 Next Steps This PR contains architecture design only (no implementation code).

After merge:

Create implementation tickets for Phase 1 (Foundation) Set up feature flags in build configuration Begin database schema implementation Follow the 8-phase rollout plan 📝 Document Details Version: 1.1 Status: Ready for Implementation Estimated Effort: 12 weeks (1 developer) Priority: High (community requested) Lines: ~1,230 lines of comprehensive documentation 🔍 Review Focus Areas When reviewing, please pay attention to:

Architecture soundness - Does the component design follow best practices? Scalability - Can this handle thousands of playlists across multiple servers? User experience - Are the defaults sensible? Is conflict resolution intuitive? Implementation feasibility - Is the phased approach realistic? API compatibility - Are the server API capabilities accurately represented?