watermelon-music/watermelon-exe

Purpose and Entry Point

Watermelon Music Desktop is a Kotlin/Compose for Desktop Windows music client. It searches a remote music catalog, resolves YouTube audio streams for native playback, presents library/radio/profile/premium experiences, and syncs account data with Supabase. Application startup and window composition begin at src/main/kotlin/com/watermelon/music/Main.kt; Gradle packages the native desktop distribution via build.gradle.kts.

UI, Navigation, and State

Compose screens are organized by product area, with ViewModels mediating user actions and UI state. Navigation is centralized in src/main/kotlin/com/watermelon/music/navigation/NavController.kt. Primary user surfaces include discovery/home (ui/home/HomeScreen.kt), search (ui/search/SearchScreen.kt), library (ui/library/LibraryScreen.kt), and radio (ui/radio/RadioScreen.kt). Authentication has an independent screen and state flow rooted in ui/auth/AuthViewModel.kt.

Catalog Discovery and Remote APIs

src/main/kotlin/com/watermelon/music/data/repository/MusicCatalogRepository.kt is the catalog boundary used to retrieve search metadata, stream-related information, and lyrics/subtitles. It integrates the Watermelon/Render-facing API contract in data/remote/WatermelonApi.kt, radio discovery through data/remote/RadioBrowserApi.kt, and Retrofit client construction in data/remote/RetrofitModule.kt. Remote DTOs are isolated in data/remote/WatermelonModels.kt before presentation/domain use.

Stream Resolution and Playback

Playback is separated from catalog lookup. src/main/kotlin/com/watermelon/music/data/remote/youtube/LocalAudioExtractor.kt and YouTubeDownloader.kt resolve YouTube or YouTube Music content into playable audio stream URLs. src/main/kotlin/com/watermelon/music/player/AudioPlayer.kt owns native/system audio output and background-capable playback. Player UI and shared playback state are represented by ui/player/PlayerViewModel.kt, with compact and immersive views in ui/player/MiniPlayer.kt and ui/player/FullScreenPlayerScreen.kt.

Account, Sync, and User Entitlements

Supabase is the account and synchronized-data boundary. src/main/kotlin/com/watermelon/music/data/SupabaseModule.kt initializes the client, while AuthRepository.kt handles authentication, profiles/display-picture storage, and user-associated synchronization. Library behavior is concentrated in LibraryEngine.kt; engagement and premium rules are isolated in GamificationEngine.kt and PremiumManager.kt. This keeps backend-account concerns outside Compose screens.

Domain and Cross-Layer Data Flow

Core app models are in src/main/kotlin/com/watermelon/music/domain/model/Song.kt, Category.kt, and Country.kt. Typical control flow is: Compose screen → ViewModel → repository/engine → remote API or Supabase → state update → screen recomposition. For playback: search/catalog selection → YouTube stream extraction → AudioPlayer → player UI state; lyrics fetched through the catalog are rendered in the full-screen player.

Runtime and External Dependencies

The material runtime is JVM/Kotlin with Compose for Desktop, packaged for the current OS through Gradle. External services are the Watermelon/Render metadata and lyrics endpoints, YouTube-derived stream sources, Radio Browser, and Supabase Auth/PostgreSQL/Storage. Release automation is defined at .github/workflows/release.yml.