# watermelon-music/watermelon-exe architecture

> Architecture diagram of the GitHub repository watermelon-music/watermelon-exe, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/watermelon-music/watermelon-exe
- Repository: https://github.com/watermelon-music/watermelon-exe

## Overview

#### 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`.

Main entry points: [`src/main/kotlin/com/watermelon/music/data/repository/MusicCatalogRepository.kt`](https://github.com/watermelon-music/watermelon-exe/blob/main/src/main/kotlin/com/watermelon/music/data/repository/MusicCatalogRepository.kt) (Music catalog repository), [`src/main/kotlin/com/watermelon/music/navigation/NavController.kt`](https://github.com/watermelon-music/watermelon-exe/blob/main/src/main/kotlin/com/watermelon/music/navigation/NavController.kt) (Navigation controller), [`src/main/kotlin/com/watermelon/music/data/remote/youtube/LocalAudioExtractor.kt`](https://github.com/watermelon-music/watermelon-exe/blob/main/src/main/kotlin/com/watermelon/music/data/remote/youtube/LocalAudioExtractor.kt) (YouTube stream extractor), [`src/main/kotlin/com/watermelon/music/Main.kt`](https://github.com/watermelon-music/watermelon-exe/blob/main/src/main/kotlin/com/watermelon/music/Main.kt) (Application entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop app"]
  node_gradle["Gradle distribution<br/>build<br/>[build.gradle.kts]"]
  node_main["Application entry<br/>Kotlin startup<br/>[Main.kt]"]
end

subgraph group_ui["Compose UI"]
  node_navigation["Navigation controller<br/>[NavController.kt]"]
  node_screens["Product screens<br/>Compose screens"]
  node_auth_vm["Auth ViewModel"]
end

subgraph group_data["Data and services"]
  node_catalog_repo["Music catalog repository"]
  node_catalog_api["Watermelon API<br/>Retrofit API"]
  node_radio_api["Radio Browser API<br/>Retrofit API"]
  node_retrofit["Retrofit module<br/>HTTP client setup"]
  node_auth_repo["Auth repository"]
  node_supabase["Supabase module<br/>client setup<br/>[SupabaseModule.kt]"]
  node_library_engine["Library engine<br/>domain engine"]
  node_entitlements["Premium and engagement<br/>domain rules"]
end

subgraph group_playback["Playback"]
  node_player_vm["Player ViewModel"]
  node_player_views["Player views<br/>Compose screens"]
  node_extractor["YouTube stream extractor<br/>stream resolver"]
  node_audio_player["Audio player<br/>native playback<br/>[AudioPlayer.kt]"]
end

subgraph group_external["External systems"]
  node_music_service{{"Watermelon / Render<br/>external API"}}
  node_youtube{{"YouTube sources<br/>external media"}}
  node_radio_browser{{"Radio Browser<br/>external API"}}
  node_supabase_cloud[("Supabase<br/>external backend")]
end

node_gradle -->|"packages"| node_main
node_main -->|"composes"| node_navigation
node_navigation -->|"routes"| node_screens
node_navigation -->|"auth flow"| node_auth_vm
node_screens -->|"catalog actions"| node_catalog_repo
node_screens -->|"library actions"| node_library_engine
node_screens -->|"premium state"| node_entitlements
node_auth_vm -->|"sign-in actions"| node_auth_repo
node_catalog_repo -->|"metadata and lyrics"| node_catalog_api
node_catalog_repo -->|"radio discovery"| node_radio_api
node_retrofit -->|"client"| node_catalog_api
node_retrofit -->|"client"| node_radio_api
node_catalog_api -->|"requests"| node_music_service
node_radio_api -->|"requests"| node_radio_browser
node_auth_repo -->|"uses"| node_supabase
node_supabase -->|"connects"| node_supabase_cloud
node_library_engine -->|"syncs user library"| node_auth_repo
node_catalog_repo -->|"selected content"| node_extractor
node_extractor -->|"resolves streams"| node_youtube
node_extractor -->|"playable URL"| node_audio_player
node_audio_player -->|"playback state"| node_player_vm
node_player_vm -->|"renders state"| node_player_views
node_catalog_repo -.->|"lyrics"| node_player_views

click node_gradle "https://github.com/watermelon-music/watermelon-exe/blob/main/build.gradle.kts"
click node_main "https://github.com/watermelon-music/watermelon-exe/blob/main/src/main/kotlin/com/watermelon/music/Main.kt"
click node_navigation "https://github.com/watermelon-music/watermelon-exe/blob/main/src/main/kotlin/com/watermelon/music/navigation/NavController.kt"
click node_catalog_repo "https://github.com/watermelon-music/watermelon-exe/blob/main/src/main/kotlin/com/watermelon/music/data/repository/MusicCatalogRepository.kt"
click node_supabase "https://github.com/watermelon-music/watermelon-exe/blob/main/src/main/kotlin/com/watermelon/music/data/SupabaseModule.kt"
click node_extractor "https://github.com/watermelon-music/watermelon-exe/blob/main/src/main/kotlin/com/watermelon/music/data/remote/youtube/LocalAudioExtractor.kt"
click node_audio_player "https://github.com/watermelon-music/watermelon-exe/blob/main/src/main/kotlin/com/watermelon/music/player/AudioPlayer.kt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gradle,node_main toneBlue
class node_navigation,node_screens,node_auth_vm toneAmber
class node_catalog_repo,node_catalog_api,node_radio_api,node_retrofit,node_auth_repo,node_supabase,node_library_engine,node_entitlements toneMint
class node_player_vm,node_player_views,node_extractor,node_audio_player toneRose
class node_music_service,node_youtube,node_radio_browser,node_supabase_cloud toneIndigo
```

## Components

### Desktop app

- [Gradle distribution](https://github.com/watermelon-music/watermelon-exe/blob/main/build.gradle.kts): build · Packages the native desktop distribution. · `build.gradle.kts`
- [Application entry](https://github.com/watermelon-music/watermelon-exe/blob/main/src/main/kotlin/com/watermelon/music/Main.kt): Kotlin startup · Starts the Compose desktop window. · `src/main/kotlin/com/watermelon/music/Main.kt`

### Compose UI

- [Navigation controller](https://github.com/watermelon-music/watermelon-exe/blob/main/src/main/kotlin/com/watermelon/music/navigation/NavController.kt): navigation · `src/main/kotlin/com/watermelon/music/navigation/NavController.kt`
- **Product screens**: Compose screens · Home, search, library, and radio surfaces.
- **Auth ViewModel**: ViewModel · Owns authentication screen state.

### Data and services

- [Music catalog repository](https://github.com/watermelon-music/watermelon-exe/blob/main/src/main/kotlin/com/watermelon/music/data/repository/MusicCatalogRepository.kt): repository · Catalog, stream metadata, and lyrics boundary. · `src/main/kotlin/com/watermelon/music/data/repository/MusicCatalogRepository.kt`
- **Watermelon API**: Retrofit API · Metadata and lyrics contract for the Watermelon/Render service.
- **Radio Browser API**: Retrofit API · Radio discovery source.
- **Retrofit module**: HTTP client setup
- **Auth repository**: repository · Authentication, profiles, storage, and account sync boundary.
- [Supabase module](https://github.com/watermelon-music/watermelon-exe/blob/main/src/main/kotlin/com/watermelon/music/data/SupabaseModule.kt): client setup · `src/main/kotlin/com/watermelon/music/data/SupabaseModule.kt`
- **Library engine**: domain engine · Concentrates library behavior.
- **Premium and engagement**: domain rules · Gamification and premium entitlement rules.

### Playback

- **Player ViewModel**: ViewModel · Shares playback state with player views.
- **Player views**: Compose screens · Mini player and full-screen player render playback and lyrics.
- [YouTube stream extractor](https://github.com/watermelon-music/watermelon-exe/blob/main/src/main/kotlin/com/watermelon/music/data/remote/youtube/LocalAudioExtractor.kt): stream resolver · Resolves YouTube content into playable audio URLs. · `src/main/kotlin/com/watermelon/music/data/remote/youtube/LocalAudioExtractor.kt`
- [Audio player](https://github.com/watermelon-music/watermelon-exe/blob/main/src/main/kotlin/com/watermelon/music/player/AudioPlayer.kt): native playback · Owns native audio output and background playback. · `src/main/kotlin/com/watermelon/music/player/AudioPlayer.kt`

### External systems

- **Watermelon / Render**: external API · Remote catalog metadata and lyrics endpoints.
- **YouTube sources**: external media · Derived audio stream source.
- **Radio Browser**: external API
- **Supabase**: external backend · Auth, PostgreSQL, and Storage.

## Connections

- Gradle distribution → Application entry: packages
- Application entry → Navigation controller: composes
- Navigation controller → Product screens: routes
- Navigation controller → Auth ViewModel: auth flow
- Product screens → Music catalog repository: catalog actions
- Product screens → Library engine: library actions
- Product screens → Premium and engagement: premium state
- Auth ViewModel → Auth repository: sign-in actions
- Music catalog repository → Watermelon API: metadata and lyrics
- Music catalog repository → Radio Browser API: radio discovery
- Retrofit module → Watermelon API: client
- Retrofit module → Radio Browser API: client
- Watermelon API → Watermelon / Render: requests
- Radio Browser API → Radio Browser: requests
- Auth repository → Supabase module: uses
- Supabase module → Supabase: connects
- Library engine → Auth repository: syncs user library
- Music catalog repository → YouTube stream extractor: selected content
- YouTube stream extractor → YouTube sources: resolves streams
- YouTube stream extractor → Audio player: playable URL
- Audio player → Player ViewModel: playback state
- Player ViewModel → Player views: renders state
- Music catalog repository → Player views: lyrics