# metrolistgroup/metrolist architecture

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

- Interactive diagram: https://gitdiagram.com/metrolistgroup/metrolist
- Repository: https://github.com/metrolistgroup/metrolist

## Overview

Metrolist is a cross-platform YouTube Music client. The main user journey is to browse or import music, select a track, and play it; the repository also exposes recognition, shared listening, casting, downloads, backups, and integrations. The graph combines documented capabilities with paths identified in the tree and SOURCE INDEX. Most implementation links are unverified because the relevant source was not excerpted, so those edges are dashed rather than asserted as observed calls.

Main entry points: [`androidApp/src/main/kotlin/com/metrolist/android/MainActivity.kt`](https://github.com/metrolistgroup/metrolist/blob/main/androidApp/src/main/kotlin/com/metrolist/android/MainActivity.kt) (Android app), [`androidApp/src/main/kotlin/com/metrolist/android/playback/MusicService.kt`](https://github.com/metrolistgroup/metrolist/blob/main/androidApp/src/main/kotlin/com/metrolist/android/playback/MusicService.kt) (Android playback), [`desktopApp/src/jvmMain/kotlin/com/metrolist/desktop/Main.kt`](https://github.com/metrolistgroup/metrolist/blob/main/desktopApp/src/jvmMain/kotlin/com/metrolist/desktop/Main.kt) (Desktop app), [`androidApp/src/main/kotlin/com/metrolist/android/recognition/MusicRecognitionService.kt`](https://github.com/metrolistgroup/metrolist/blob/main/androidApp/src/main/kotlin/com/metrolist/android/recognition/MusicRecognitionService.kt) (Music recognition)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App experience"]
  node_android["Android app<br/>[MainActivity.kt]"]
  node_desktop["Desktop app<br/>[Main.kt]"]
  node_ios["iOS app"]
  node_artwork["Animated artwork"]
end

subgraph group_playback["Playback and storage"]
  node_androidplayback["Android playback<br/>[MusicService.kt]"]
  node_audiocache[("Audio cache")]
  node_downloads["Android downloads"]
  node_desktopdownloads["Desktop downloads<br/>[DownloadManager.kt]"]
end

subgraph group_shared["Shared platform services"]
  node_settings["Preferences<br/>[Settings.kt]"]
  node_musicdb[("Music database<br/>[MusicDatabase.kt]")]
  node_musicvideo["Video resolver"]
  node_resource["Playback resource"]
end

subgraph group_extras["Discovery and integrations"]
  node_playlistimport["Playlist import"]
  node_recognition["Music recognition"]
  node_together["Listen Together"]
  node_deviceconnect["Device connection"]
  node_cast["Android cast discovery"]
  node_backup["Backup and restore"]
end

node_user(("Listener"))
node_youtube{{"YouTube Music"}}
node_shazam{{"Shazam"}}
node_castdevices{{"Cast devices"}}

node_user -->|"uses"| node_android
node_user -->|"uses"| node_desktop
node_user -->|"uses"| node_ios
node_android -.->|"starts playback"| node_androidplayback
node_desktop -.->|"requests music"| node_youtube
node_androidplayback -->|"streams music"| node_youtube
node_androidplayback -.->|"uses stream data"| node_resource
node_musicvideo -.->|"resolves video"| node_resource
node_androidplayback -.->|"uses cache"| node_audiocache
node_androidplayback -.->|"persists playback"| node_musicdb
node_android -.->|"downloads tracks"| node_downloads
node_desktop -.->|"downloads tracks"| node_desktopdownloads
node_android -->|"imports playlists"| node_playlistimport
node_android -->|"recognizes music"| node_recognition
node_recognition -->|"matches audio"| node_shazam
node_user -->|"shares playback"| node_together
node_user -->|"connects devices"| node_deviceconnect
node_android -.->|"discovers devices"| node_cast
node_cast -.->|"discovers"| node_castdevices
node_user -->|"backs up library"| node_backup
node_android -.->|"reads preferences"| node_settings
node_android -.->|"loads artwork"| node_artwork

click node_android "https://github.com/metrolistgroup/metrolist/blob/main/androidApp/src/main/kotlin/com/metrolist/android/MainActivity.kt"
click node_desktop "https://github.com/metrolistgroup/metrolist/blob/main/desktopApp/src/jvmMain/kotlin/com/metrolist/desktop/Main.kt"
click node_ios "https://github.com/metrolistgroup/metrolist/blob/main/shared/src/iosMain/kotlin/com/metrolist/shared/MainViewController.kt"
click node_settings "https://github.com/metrolistgroup/metrolist/blob/main/shared/src/commonMain/kotlin/com/metrolist/shared/settings/Settings.kt"
click node_musicdb "https://github.com/metrolistgroup/metrolist/blob/main/shared/src/commonMain/kotlin/com/metrolist/shared/db/MusicDatabase.kt"
click node_musicvideo "https://github.com/metrolistgroup/metrolist/blob/main/shared/src/commonMain/kotlin/com/metrolist/shared/api/musicvideo/MusicVideoResolver.kt"
click node_resource "https://github.com/metrolistgroup/metrolist/blob/main/shared/src/commonMain/kotlin/com/metrolist/shared/youtube/playback/PlaybackResource.kt"
click node_androidplayback "https://github.com/metrolistgroup/metrolist/blob/main/androidApp/src/main/kotlin/com/metrolist/android/playback/MusicService.kt"
click node_audiocache "https://github.com/metrolistgroup/metrolist/blob/main/androidApp/src/main/kotlin/com/metrolist/android/playback/AudioCacheManager.kt"
click node_downloads "https://github.com/metrolistgroup/metrolist/blob/main/androidApp/src/main/kotlin/com/metrolist/android/playback/SongDownloadManager.kt"
click node_desktopdownloads "https://github.com/metrolistgroup/metrolist/blob/main/desktopApp/src/jvmMain/kotlin/com/metrolist/desktop/storage/DownloadManager.kt"
click node_artwork "https://github.com/metrolistgroup/metrolist/blob/main/shared/src/commonMain/kotlin/com/metrolist/shared/api/artwork/AnimatedArtworkService.kt"
click node_playlistimport "https://github.com/metrolistgroup/metrolist/blob/main/androidApp/src/main/kotlin/com/metrolist/android/playlistimport/AndroidPlaylistImportService.kt"
click node_recognition "https://github.com/metrolistgroup/metrolist/blob/main/androidApp/src/main/kotlin/com/metrolist/android/recognition/MusicRecognitionService.kt"
click node_together "https://github.com/metrolistgroup/metrolist/blob/main/shared/src/commonMain/kotlin/com/metrolist/shared/listentogether/ListenTogetherManager.kt"
click node_deviceconnect "https://github.com/metrolistgroup/metrolist/blob/main/shared/src/commonMain/kotlin/com/metrolist/shared/deviceconnect/DeviceConnectManager.kt"
click node_cast "https://github.com/metrolistgroup/metrolist/blob/main/androidApp/src/main/kotlin/com/metrolist/android/cast/AndroidMdnsCastDiscovery.kt"
click node_backup "https://github.com/metrolistgroup/metrolist/blob/main/androidApp/src/main/kotlin/com/metrolist/android/backup/BackupRestoreManager.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_android,node_desktop,node_ios,node_artwork toneBlue
class node_androidplayback,node_audiocache,node_downloads,node_desktopdownloads toneAmber
class node_settings,node_musicdb,node_musicvideo,node_resource toneMint
class node_playlistimport,node_recognition,node_together,node_deviceconnect,node_cast,node_backup toneRose
class node_user,node_youtube,node_shazam,node_castdevices toneIndigo
```

## Components

### App experience

- [Android app](https://github.com/metrolistgroup/metrolist/blob/main/androidApp/src/main/kotlin/com/metrolist/android/MainActivity.kt): `androidApp/src/main/kotlin/com/metrolist/android/MainActivity.kt`
- [Desktop app](https://github.com/metrolistgroup/metrolist/blob/main/desktopApp/src/jvmMain/kotlin/com/metrolist/desktop/Main.kt): `desktopApp/src/jvmMain/kotlin/com/metrolist/desktop/Main.kt`
- [iOS app](https://github.com/metrolistgroup/metrolist/blob/main/shared/src/iosMain/kotlin/com/metrolist/shared/MainViewController.kt): `shared/src/iosMain/kotlin/com/metrolist/shared/MainViewController.kt`
- [Animated artwork](https://github.com/metrolistgroup/metrolist/blob/main/shared/src/commonMain/kotlin/com/metrolist/shared/api/artwork/AnimatedArtworkService.kt): `shared/src/commonMain/kotlin/com/metrolist/shared/api/artwork/AnimatedArtworkService.kt`

### Playback and storage

- [Android playback](https://github.com/metrolistgroup/metrolist/blob/main/androidApp/src/main/kotlin/com/metrolist/android/playback/MusicService.kt): `androidApp/src/main/kotlin/com/metrolist/android/playback/MusicService.kt`
- [Audio cache](https://github.com/metrolistgroup/metrolist/blob/main/androidApp/src/main/kotlin/com/metrolist/android/playback/AudioCacheManager.kt): `androidApp/src/main/kotlin/com/metrolist/android/playback/AudioCacheManager.kt`
- [Android downloads](https://github.com/metrolistgroup/metrolist/blob/main/androidApp/src/main/kotlin/com/metrolist/android/playback/SongDownloadManager.kt): `androidApp/src/main/kotlin/com/metrolist/android/playback/SongDownloadManager.kt`
- [Desktop downloads](https://github.com/metrolistgroup/metrolist/blob/main/desktopApp/src/jvmMain/kotlin/com/metrolist/desktop/storage/DownloadManager.kt): `desktopApp/src/jvmMain/kotlin/com/metrolist/desktop/storage/DownloadManager.kt`

### Shared platform services

- [Preferences](https://github.com/metrolistgroup/metrolist/blob/main/shared/src/commonMain/kotlin/com/metrolist/shared/settings/Settings.kt): `shared/src/commonMain/kotlin/com/metrolist/shared/settings/Settings.kt`
- [Music database](https://github.com/metrolistgroup/metrolist/blob/main/shared/src/commonMain/kotlin/com/metrolist/shared/db/MusicDatabase.kt): `shared/src/commonMain/kotlin/com/metrolist/shared/db/MusicDatabase.kt`
- [Video resolver](https://github.com/metrolistgroup/metrolist/blob/main/shared/src/commonMain/kotlin/com/metrolist/shared/api/musicvideo/MusicVideoResolver.kt): `shared/src/commonMain/kotlin/com/metrolist/shared/api/musicvideo/MusicVideoResolver.kt`
- [Playback resource](https://github.com/metrolistgroup/metrolist/blob/main/shared/src/commonMain/kotlin/com/metrolist/shared/youtube/playback/PlaybackResource.kt): `shared/src/commonMain/kotlin/com/metrolist/shared/youtube/playback/PlaybackResource.kt`

### Discovery and integrations

- [Playlist import](https://github.com/metrolistgroup/metrolist/blob/main/androidApp/src/main/kotlin/com/metrolist/android/playlistimport/AndroidPlaylistImportService.kt): `androidApp/src/main/kotlin/com/metrolist/android/playlistimport/AndroidPlaylistImportService.kt`
- [Music recognition](https://github.com/metrolistgroup/metrolist/blob/main/androidApp/src/main/kotlin/com/metrolist/android/recognition/MusicRecognitionService.kt): `androidApp/src/main/kotlin/com/metrolist/android/recognition/MusicRecognitionService.kt`
- [Listen Together](https://github.com/metrolistgroup/metrolist/blob/main/shared/src/commonMain/kotlin/com/metrolist/shared/listentogether/ListenTogetherManager.kt): `shared/src/commonMain/kotlin/com/metrolist/shared/listentogether/ListenTogetherManager.kt`
- [Device connection](https://github.com/metrolistgroup/metrolist/blob/main/shared/src/commonMain/kotlin/com/metrolist/shared/deviceconnect/DeviceConnectManager.kt): `shared/src/commonMain/kotlin/com/metrolist/shared/deviceconnect/DeviceConnectManager.kt`
- [Android cast discovery](https://github.com/metrolistgroup/metrolist/blob/main/androidApp/src/main/kotlin/com/metrolist/android/cast/AndroidMdnsCastDiscovery.kt): `androidApp/src/main/kotlin/com/metrolist/android/cast/AndroidMdnsCastDiscovery.kt`
- [Backup and restore](https://github.com/metrolistgroup/metrolist/blob/main/androidApp/src/main/kotlin/com/metrolist/android/backup/BackupRestoreManager.kt): `androidApp/src/main/kotlin/com/metrolist/android/backup/BackupRestoreManager.kt`

### Other components

- **Listener**
- **YouTube Music**
- **Shazam**
- **Cast devices**

## Connections

- Listener → Android app: uses (evidence: `README.md`)
- Listener → Desktop app: uses (evidence: `README.md`)
- Listener → iOS app: uses (evidence: `README.md`)
- Android app → Android playback: starts playback (evidence: `androidApp/src/main/kotlin/com/metrolist/android/playback/MusicService.kt`)
- Desktop app → YouTube Music: requests music
- Android playback → YouTube Music: streams music (evidence: `README.md`)
- Android playback → Playback resource: uses stream data (evidence: `androidApp/src/main/kotlin/com/metrolist/android/playback/MusicService.kt`)
- Video resolver → Playback resource: resolves video
- Android playback → Audio cache: uses cache
- Android playback → Music database: persists playback (evidence: `androidApp/src/main/kotlin/com/metrolist/android/playback/MusicService.kt`)
- Android app → Android downloads: downloads tracks (evidence: `androidApp/src/main/kotlin/com/metrolist/android/playback/SongDownloadManager.kt`)
- Desktop app → Desktop downloads: downloads tracks (evidence: `desktopApp/src/jvmMain/kotlin/com/metrolist/desktop/Main.kt`)
- Android app → Playlist import: imports playlists (evidence: `README.md`)
- Android app → Music recognition: recognizes music (evidence: `README.md`)
- Music recognition → Shazam: matches audio (evidence: `README.md`)
- Listener → Listen Together: shares playback (evidence: `README.md`)
- Listener → Device connection: connects devices (evidence: `README.md`)
- Android app → Android cast discovery: discovers devices
- Android cast discovery → Cast devices: discovers
- Listener → Backup and restore: backs up library (evidence: `README.md`)
- Android app → Preferences: reads preferences (evidence: `androidApp/src/main/kotlin/com/metrolist/android/MainActivity.kt`)
- Android app → Animated artwork: loads artwork
