# watermelon-music/watermelon-apk architecture

> Architecture diagram of the GitHub repository watermelon-music/watermelon-apk, 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-apk
- Repository: https://github.com/watermelon-music/watermelon-apk

## Overview

#### Purpose and runtime
Watermelon is a modular Android 8.0+ music-streaming client written in Kotlin. It uses Jetpack Compose for UI, Media3/ExoPlayer for playback, Coroutines/Flow for state, and Hilt for dependency injection. Gradle assembles a single application shell plus feature, domain, data, and core modules.  
Paths: `app/src/main/java/com/watermelon/app/WatermelonApplication.kt`, `app/build.gradle.kts`, `settings.gradle.kts`

#### Application entry and UI composition
`MainActivity` is the Android/UI entry point. The app shell owns top-level navigation, bottom navigation, configuration/ads/updating hooks, and integrates independently built feature Compose screens. Routes are shared through `core/navigation`; features expose screen/ViewModel pairs and should not directly own remote or database plumbing.  
Paths: `app/src/main/java/com/watermelon/app/MainActivity.kt`, `app/src/main/java/com/watermelon/app/navigation/WatermelonNavHost.kt`, `core/navigation/src/main/java/com/watermelon/core/navigation/Routes.kt`

#### Feature layer and state flow
Feature modules implement presentation workflows: home/discovery, search, library, playlists, downloads, auth, settings, and player. Compose observes ViewModel state; ViewModels invoke domain repository contracts, preserving unidirectional UI → ViewModel → repository → state flow. App-owned screens cover radio, profiles, premium, onboarding, and artists.  
Paths: `feature-home/src/main/java/com/watermelon/feature/home/HomeViewModel.kt`, `feature-search/src/main/java/com/watermelon/feature/search/SearchViewModel.kt`, `feature-player/src/main/java/com/watermelon/feature/player/PlayerViewModel.kt`

#### Playback, queue, and autoplay boundary
Playback is process/service-oriented rather than tied to a screen: `PlaybackService` hosts media playback, while player UI dispatches commands and observes playback/queue state. `QueueAwareForwardingPlayer` customizes queue advancement. When queues exhaust, candidate fetching and the domain autoplay engine use listening signals, scoring, and transition tracking to select follow-on songs.  
Paths: `app/src/main/java/com/watermelon/app/PlaybackService.kt`, `feature-player/src/main/java/com/watermelon/feature/player/CandidateFetcher.kt`, `domain/src/main/java/com/watermelon/domain/autoplay/AutoplayEngine.kt`

#### Domain contracts and business model
The `domain` module is the dependency boundary: it defines music, playlist, user, radio, download, and remote-config models plus repository interfaces. It also contains recommendation rules and a playback command abstraction, allowing presentation to depend on stable contracts rather than concrete APIs, Room, or extraction engines.  
Paths: `domain/src/main/java/com/watermelon/domain/model/Song.kt`, `domain/src/main/java/com/watermelon/domain/repository/MusicRepository.kt`, `domain/src/main/java/com/watermelon/domain/player/PlaybackCommandDispatcher.kt`

#### Data integration and persistence
`data` implements domain contracts and wires sources through Hilt modules. Room persists cached songs/playlists, downloads, play history, skips, transitions, scoring, and user actions—supporting offline playback and local recommendation inputs. Repositories mediate cache/local state and remote responses.  
Paths: `data/src/main/java/com/watermelon/data/local/AppDatabase.kt`, `data/src/main/java/com/watermelon/data/repository/MusicRepositoryImpl.kt`, `data/src/main/java/com/watermelon/data/di/RepositoryModule.kt`

#### External services and operational integrations
Network adapters use Retrofit/OkHttp for the companion Watermelon Node/Express API (search/audio extraction), YouTube/NewPipe extraction, Audius, Jamendo, Podcast Index, lyrics, and Radio Browser. Supabase provides auth and cloud social/playlist/profile data; SQL migrations define its expected schema. Payments support premium flows; Google services config and an in-app updater are app-level integrations.  
Paths: `data/src/main/java/com/watermelon/data/remote/watermelon/WatermelonApi.kt`, `data/src/main/java/com/watermelon/data/di/SupabaseModule.kt`, `supabase_setup.sql`

#### Shared UX and release boundary
The design-system module centralizes Compose theme, responsive window sizing, animation, and reusable UI primitives. Release automation is GitHub Actions based; the Android app’s updater checks and installs newer APK releases.  
Paths: `core/designsystem/src/main/java/com/watermelon/core/designsystem/theme/Theme.kt`, `app/src/main/java/com/watermelon/app/updater/AppUpdater.kt`, `.github/workflows/release.yml`

Main entry points: [`data/src/main/java/com/watermelon/data/repository/MusicRepositoryImpl.kt`](https://github.com/watermelon-music/watermelon-apk/blob/main/data/src/main/java/com/watermelon/data/repository/MusicRepositoryImpl.kt) (Repository implementations), [`app/src/main/java/com/watermelon/app/WatermelonApplication.kt`](https://github.com/watermelon-music/watermelon-apk/blob/main/app/src/main/java/com/watermelon/app/WatermelonApplication.kt) (Watermelon application), [`app/src/main/java/com/watermelon/app/MainActivity.kt`](https://github.com/watermelon-music/watermelon-apk/blob/main/app/src/main/java/com/watermelon/app/MainActivity.kt) (Main activity & app shell), [`app/src/main/java/com/watermelon/app/navigation/WatermelonNavHost.kt`](https://github.com/watermelon-music/watermelon-apk/blob/main/app/src/main/java/com/watermelon/app/navigation/WatermelonNavHost.kt) (Navigation host)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Android app"]
  node_gradle{{"Gradle module assembly<br/>build"}}
  node_application["Watermelon application<br/>Android application"]
  node_main_activity["Main activity &amp; app shell<br/>Compose shell<br/>[MainActivity.kt]"]
  node_nav_host["Navigation host<br/>Compose navigation"]
  node_playback_service["Playback service<br/>Media3 service<br/>[PlaybackService.kt]"]
  node_updater["APK updater<br/>app integration<br/>[AppUpdater.kt]"]
end

subgraph group_presentation["Presentation"]
  node_routes["Shared routes<br/>navigation contract<br/>[Routes.kt]"]
  node_features["Feature screens<br/>Compose features<br/>[HomeViewModel.kt]"]
  node_viewmodels["Feature ViewModels<br/>state holders<br/>[SearchViewModel.kt]"]
  node_player_ui["Player UI &amp; commands<br/>player feature<br/>[PlayerViewModel.kt]"]
  node_design_system["Design system<br/>shared Compose UI<br/>[Theme.kt]"]
end

subgraph group_domain["Domain"]
  node_domain_contracts["Models &amp; repository contracts<br/>domain boundary<br/>[MusicRepository.kt]"]
  node_playback_commands["Playback command contract<br/>domain player API"]
  node_autoplay["Autoplay engine<br/>recommendation rules<br/>[AutoplayEngine.kt]"]
end

subgraph group_data["Data &amp; integrations"]
  node_repositories["Repository implementations<br/>data repositories"]
  node_room[("Room cache &amp; listening data<br/>local database<br/>[AppDatabase.kt]")]
  node_remote["Music service adapters<br/>Retrofit/OkHttp adapters<br/>[WatermelonApi.kt]"]
  node_supabase[("Supabase cloud data<br/>auth &amp; social backend<br/>[SupabaseModule.kt]")]
end

subgraph group_platform["Platform &amp; delivery"]
  node_release{{"Release automation<br/>GitHub Actions<br/>[release.yml]"}}
end

node_gradle -->|"assembles"| node_application
node_application -->|"starts"| node_main_activity
node_main_activity -->|"hosts"| node_nav_host
node_nav_host -->|"uses"| node_routes
node_nav_host -->|"navigates to"| node_features
node_features -->|"observes state from"| node_viewmodels
node_features -->|"renders with"| node_design_system
node_viewmodels -->|"depends on"| node_domain_contracts
node_player_ui -->|"dispatches"| node_playback_commands
node_player_ui -->|"observes and controls"| node_playback_service
node_playback_service -->|"requests next song"| node_autoplay
node_autoplay -->|"uses listening inputs"| node_repositories
node_repositories -->|"implements"| node_domain_contracts
node_repositories -->|"reads and writes"| node_room
node_repositories -->|"fetches catalog and audio"| node_remote
node_repositories -->|"syncs auth and cloud data"| node_supabase
node_application -.->|"Hilt wires"| node_repositories
node_main_activity -->|"integrates"| node_updater
node_updater -.->|"checks releases"| node_release

click node_gradle "https://github.com/watermelon-music/watermelon-apk/blob/main/settings.gradle.kts"
click node_application "https://github.com/watermelon-music/watermelon-apk/blob/main/app/src/main/java/com/watermelon/app/WatermelonApplication.kt"
click node_main_activity "https://github.com/watermelon-music/watermelon-apk/blob/main/app/src/main/java/com/watermelon/app/MainActivity.kt"
click node_nav_host "https://github.com/watermelon-music/watermelon-apk/blob/main/app/src/main/java/com/watermelon/app/navigation/WatermelonNavHost.kt"
click node_playback_service "https://github.com/watermelon-music/watermelon-apk/blob/main/app/src/main/java/com/watermelon/app/PlaybackService.kt"
click node_updater "https://github.com/watermelon-music/watermelon-apk/blob/main/app/src/main/java/com/watermelon/app/updater/AppUpdater.kt"
click node_routes "https://github.com/watermelon-music/watermelon-apk/blob/main/core/navigation/src/main/java/com/watermelon/core/navigation/Routes.kt"
click node_features "https://github.com/watermelon-music/watermelon-apk/blob/main/feature-home/src/main/java/com/watermelon/feature/home/HomeViewModel.kt"
click node_viewmodels "https://github.com/watermelon-music/watermelon-apk/blob/main/feature-search/src/main/java/com/watermelon/feature/search/SearchViewModel.kt"
click node_player_ui "https://github.com/watermelon-music/watermelon-apk/blob/main/feature-player/src/main/java/com/watermelon/feature/player/PlayerViewModel.kt"
click node_design_system "https://github.com/watermelon-music/watermelon-apk/blob/main/core/designsystem/src/main/java/com/watermelon/core/designsystem/theme/Theme.kt"
click node_domain_contracts "https://github.com/watermelon-music/watermelon-apk/blob/main/domain/src/main/java/com/watermelon/domain/repository/MusicRepository.kt"
click node_playback_commands "https://github.com/watermelon-music/watermelon-apk/blob/main/domain/src/main/java/com/watermelon/domain/player/PlaybackCommandDispatcher.kt"
click node_autoplay "https://github.com/watermelon-music/watermelon-apk/blob/main/domain/src/main/java/com/watermelon/domain/autoplay/AutoplayEngine.kt"
click node_repositories "https://github.com/watermelon-music/watermelon-apk/blob/main/data/src/main/java/com/watermelon/data/repository/MusicRepositoryImpl.kt"
click node_room "https://github.com/watermelon-music/watermelon-apk/blob/main/data/src/main/java/com/watermelon/data/local/AppDatabase.kt"
click node_remote "https://github.com/watermelon-music/watermelon-apk/blob/main/data/src/main/java/com/watermelon/data/remote/watermelon/WatermelonApi.kt"
click node_supabase "https://github.com/watermelon-music/watermelon-apk/blob/main/data/src/main/java/com/watermelon/data/di/SupabaseModule.kt"
click node_release "https://github.com/watermelon-music/watermelon-apk/blob/main/.github/workflows/release.yml"

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_application,node_main_activity,node_nav_host,node_playback_service,node_updater toneBlue
class node_routes,node_features,node_viewmodels,node_player_ui,node_design_system toneAmber
class node_domain_contracts,node_playback_commands,node_autoplay toneMint
class node_repositories,node_room,node_remote,node_supabase toneRose
class node_release toneIndigo
```

## Components

### Android app

- [Gradle module assembly](https://github.com/watermelon-music/watermelon-apk/blob/main/settings.gradle.kts): build · Builds the app shell and modular feature layers. · `settings.gradle.kts`
- [Watermelon application](https://github.com/watermelon-music/watermelon-apk/blob/main/app/src/main/java/com/watermelon/app/WatermelonApplication.kt): Android application · Initializes the Android process and dependency graph. · `app/src/main/java/com/watermelon/app/WatermelonApplication.kt`
- [Main activity & app shell](https://github.com/watermelon-music/watermelon-apk/blob/main/app/src/main/java/com/watermelon/app/MainActivity.kt): Compose shell · Hosts top-level navigation, bottom navigation, and app integrations. · `app/src/main/java/com/watermelon/app/MainActivity.kt`
- [Navigation host](https://github.com/watermelon-music/watermelon-apk/blob/main/app/src/main/java/com/watermelon/app/navigation/WatermelonNavHost.kt): Compose navigation · `app/src/main/java/com/watermelon/app/navigation/WatermelonNavHost.kt`
- [Playback service](https://github.com/watermelon-music/watermelon-apk/blob/main/app/src/main/java/com/watermelon/app/PlaybackService.kt): Media3 service · Process-oriented owner of media playback and queue state. · `app/src/main/java/com/watermelon/app/PlaybackService.kt`
- [APK updater](https://github.com/watermelon-music/watermelon-apk/blob/main/app/src/main/java/com/watermelon/app/updater/AppUpdater.kt): app integration · Checks and installs newer APK releases. · `app/src/main/java/com/watermelon/app/updater/AppUpdater.kt`

### Presentation

- [Shared routes](https://github.com/watermelon-music/watermelon-apk/blob/main/core/navigation/src/main/java/com/watermelon/core/navigation/Routes.kt): navigation contract · `core/navigation/src/main/java/com/watermelon/core/navigation/Routes.kt`
- [Feature screens](https://github.com/watermelon-music/watermelon-apk/blob/main/feature-home/src/main/java/com/watermelon/feature/home/HomeViewModel.kt): Compose features · Home, search, library, playlists, downloads, auth, settings, and player workflows. · `feature-home/src/main/java/com/watermelon/feature/home/HomeViewModel.kt`
- [Feature ViewModels](https://github.com/watermelon-music/watermelon-apk/blob/main/feature-search/src/main/java/com/watermelon/feature/search/SearchViewModel.kt): state holders · Invoke repository contracts and expose Flow-backed UI state. · `feature-search/src/main/java/com/watermelon/feature/search/SearchViewModel.kt`
- [Player UI & commands](https://github.com/watermelon-music/watermelon-apk/blob/main/feature-player/src/main/java/com/watermelon/feature/player/PlayerViewModel.kt): player feature · Dispatches playback commands and observes service state. · `feature-player/src/main/java/com/watermelon/feature/player/PlayerViewModel.kt`
- [Design system](https://github.com/watermelon-music/watermelon-apk/blob/main/core/designsystem/src/main/java/com/watermelon/core/designsystem/theme/Theme.kt): shared Compose UI · Provides theme, responsive sizing, animation, and UI primitives. · `core/designsystem/src/main/java/com/watermelon/core/designsystem/theme/Theme.kt`

### Domain

- [Models & repository contracts](https://github.com/watermelon-music/watermelon-apk/blob/main/domain/src/main/java/com/watermelon/domain/repository/MusicRepository.kt): domain boundary · Stable music, playlist, user, radio, download, and config contracts. · `domain/src/main/java/com/watermelon/domain/repository/MusicRepository.kt`
- [Playback command contract](https://github.com/watermelon-music/watermelon-apk/blob/main/domain/src/main/java/com/watermelon/domain/player/PlaybackCommandDispatcher.kt): domain player API · `domain/src/main/java/com/watermelon/domain/player/PlaybackCommandDispatcher.kt`
- [Autoplay engine](https://github.com/watermelon-music/watermelon-apk/blob/main/domain/src/main/java/com/watermelon/domain/autoplay/AutoplayEngine.kt): recommendation rules · Scores listening signals and selects follow-on songs. · `domain/src/main/java/com/watermelon/domain/autoplay/AutoplayEngine.kt`

### Data & integrations

- [Repository implementations](https://github.com/watermelon-music/watermelon-apk/blob/main/data/src/main/java/com/watermelon/data/repository/MusicRepositoryImpl.kt): data repositories · Mediate remote responses, cache, and local state. · `data/src/main/java/com/watermelon/data/repository/MusicRepositoryImpl.kt`
- [Room cache & listening data](https://github.com/watermelon-music/watermelon-apk/blob/main/data/src/main/java/com/watermelon/data/local/AppDatabase.kt): local database · Stores offline media, playlists, history, skips, transitions, scores, and actions. · `data/src/main/java/com/watermelon/data/local/AppDatabase.kt`
- [Music service adapters](https://github.com/watermelon-music/watermelon-apk/blob/main/data/src/main/java/com/watermelon/data/remote/watermelon/WatermelonApi.kt): Retrofit/OkHttp adapters · Connects Watermelon API, extractors, catalogs, lyrics, podcasts, and radio. · `data/src/main/java/com/watermelon/data/remote/watermelon/WatermelonApi.kt`
- [Supabase cloud data](https://github.com/watermelon-music/watermelon-apk/blob/main/data/src/main/java/com/watermelon/data/di/SupabaseModule.kt): auth & social backend · Provides authentication and cloud profiles, social data, and playlists. · `data/src/main/java/com/watermelon/data/di/SupabaseModule.kt`

### Platform & delivery

- [Release automation](https://github.com/watermelon-music/watermelon-apk/blob/main/.github/workflows/release.yml): GitHub Actions · Publishes APK releases consumed by the updater. · `.github/workflows/release.yml`

## Connections

- Gradle module assembly → Watermelon application: assembles
- Watermelon application → Main activity & app shell: starts
- Main activity & app shell → Navigation host: hosts
- Navigation host → Shared routes: uses
- Navigation host → Feature screens: navigates to
- Feature screens → Feature ViewModels: observes state from
- Feature screens → Design system: renders with
- Feature ViewModels → Models & repository contracts: depends on
- Player UI & commands → Playback command contract: dispatches
- Player UI & commands → Playback service: observes and controls
- Playback service → Autoplay engine: requests next song
- Autoplay engine → Repository implementations: uses listening inputs
- Repository implementations → Models & repository contracts: implements
- Repository implementations → Room cache & listening data: reads and writes
- Repository implementations → Music service adapters: fetches catalog and audio
- Repository implementations → Supabase cloud data: syncs auth and cloud data
- Watermelon application → Repository implementations: Hilt wires
- Main activity & app shell → APK updater: integrates
- APK updater → Release automation: checks releases