# inuhepott/archivetune architecture

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

- Interactive diagram: https://gitdiagram.com/inuhepott/archivetune
- Repository: https://github.com/inuhepott/archivetune

## Overview

ArchiveTune is an Android YouTube Music-oriented player with local-library support. The main user journey is browsing or searching music, turning results into playable queue items, and listening through the background media service; lyrics, discovery, statistics, and social integrations extend that experience. The graph also preserves documented audio, account, and customization capabilities. Source excerpts are partial, so some subsystem links are documented by the README or reference index rather than verified call sites; uncertain links are omitted.

Main entry points: [`app/src/main/kotlin/moe/koiverse/archivetune/playback/MusicService.kt`](https://github.com/inuhepott/archivetune/blob/main/app/src/main/kotlin/moe/koiverse/archivetune/playback/MusicService.kt) (Music service), [`innertube/src/main/kotlin/moe/koiverse/archivetune/innertube`](https://github.com/inuhepott/archivetune/tree/main/innertube/src/main/kotlin/moe/koiverse/archivetune/innertube) (YouTube Music access), [`app/src/main/kotlin/moe/koiverse/archivetune/db/MusicDatabase.kt`](https://github.com/inuhepott/archivetune/blob/main/app/src/main/kotlin/moe/koiverse/archivetune/db/MusicDatabase.kt) (Music database), [`app/src/main/kotlin/moe/koiverse/archivetune/lyrics/LyricsPreloadManager.kt`](https://github.com/inuhepott/archivetune/blob/main/app/src/main/kotlin/moe/koiverse/archivetune/lyrics/LyricsPreloadManager.kt) (Lyrics preloader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App experience"]
  node_app_ui["Browse and search"]
  node_player_ui["Player interface<br/>[Player.kt]"]
  node_main["App shell<br/>[MainActivity.kt]"]
end

subgraph group_music["Music access"]
  node_youtube["YouTube Music access"]
  node_metadata["Track metadata<br/>[MediaMetadata.kt]"]
  node_local_scan["Local music scan"]
end

subgraph group_playback["Playback"]
  node_music_service["Music service<br/>[MusicService.kt]"]
  node_queues["Playback queues"]
  node_audio["Audio processing"]
  node_downloads["Offline downloads"]
end

subgraph group_lyrics["Lyrics and discovery"]
  node_lyrics_fetch["Lyrics retrieval<br/>[LyricsHelper.kt]"]
  node_lyrics_preload["Lyrics preloader"]
  node_lyrics_ui["Synced lyrics<br/>[Lyrics.kt]"]
  node_ai_text["Lyrics translation<br/>[AiTextService.kt]"]
  node_recognition["Music recognition"]
end

subgraph group_state["Library and integrations"]
  node_database[("Music database<br/>[MusicDatabase.kt]")]
  node_statistics["Listening statistics<br/>[StatsScreen.kt]"]
  node_social["Listening integrations<br/>[ScrobbleManager.kt]"]
  node_together["Shared listening"]
end

node_listener(("Listener"))
node_youtube_api(("YouTube service"))
node_external_services(("External services"))

node_listener -->|"opens"| node_main
node_main -.->|"presents"| node_app_ui
node_listener -->|"browses"| node_app_ui
node_app_ui -.->|"requests catalog"| node_youtube
node_youtube -.->|"requests data"| node_youtube_api
node_youtube -.->|"maps results"| node_metadata
node_local_scan -.->|"indexes songs"| node_database
node_metadata -.->|"supplies tracks"| node_music_service
node_music_service -->|"uses"| node_youtube
node_music_service -->|"reads and writes"| node_database
node_music_service -->|"preloads lyrics"| node_lyrics_preload
node_music_service -.->|"uses queue"| node_queues
node_music_service -->|"processes audio"| node_audio
node_music_service -->|"starts downloads"| node_downloads
node_music_service -.->|"drives playback"| node_player_ui
node_lyrics_preload -->|"checks and caches"| node_database
node_lyrics_preload -.->|"fetches lyrics"| node_lyrics_fetch
node_lyrics_fetch -.->|"queries providers"| node_external_services
node_lyrics_ui -.->|"displays lyrics"| node_lyrics_fetch
node_lyrics_ui -.->|"translates text"| node_ai_text
node_recognition -.->|"identifies music"| node_external_services
node_statistics -.->|"reads history"| node_database
node_social -.->|"syncs listening"| node_external_services
node_together -.->|"coordinates playback"| node_external_services
node_listener -->|"views lyrics"| node_lyrics_ui
node_listener -->|"recognizes music"| node_recognition
node_listener -->|"reviews listening"| node_statistics

click node_app_ui "https://github.com/inuhepott/archivetune/tree/main/app/src/main/kotlin/moe/koiverse/archivetune/ui/screens"
click node_player_ui "https://github.com/inuhepott/archivetune/blob/main/app/src/main/kotlin/moe/koiverse/archivetune/ui/player/Player.kt"
click node_main "https://github.com/inuhepott/archivetune/blob/main/app/src/main/kotlin/moe/koiverse/archivetune/MainActivity.kt"
click node_youtube "https://github.com/inuhepott/archivetune/tree/main/innertube/src/main/kotlin/moe/koiverse/archivetune/innertube"
click node_metadata "https://github.com/inuhepott/archivetune/blob/main/app/src/main/kotlin/moe/koiverse/archivetune/models/MediaMetadata.kt"
click node_local_scan "https://github.com/inuhepott/archivetune/blob/main/app/src/main/kotlin/moe/koiverse/archivetune/localmedia/LocalSongScanner.kt"
click node_music_service "https://github.com/inuhepott/archivetune/blob/main/app/src/main/kotlin/moe/koiverse/archivetune/playback/MusicService.kt"
click node_queues "https://github.com/inuhepott/archivetune/tree/main/app/src/main/kotlin/moe/koiverse/archivetune/playback/queues"
click node_audio "https://github.com/inuhepott/archivetune/tree/main/app/src/main/kotlin/moe/koiverse/archivetune/playback"
click node_downloads "https://github.com/inuhepott/archivetune/blob/main/app/src/main/kotlin/moe/koiverse/archivetune/playback/ExoDownloadService.kt"
click node_database "https://github.com/inuhepott/archivetune/blob/main/app/src/main/kotlin/moe/koiverse/archivetune/db/MusicDatabase.kt"
click node_lyrics_fetch "https://github.com/inuhepott/archivetune/blob/main/app/src/main/kotlin/moe/koiverse/archivetune/lyrics/LyricsHelper.kt"
click node_lyrics_preload "https://github.com/inuhepott/archivetune/blob/main/app/src/main/kotlin/moe/koiverse/archivetune/lyrics/LyricsPreloadManager.kt"
click node_lyrics_ui "https://github.com/inuhepott/archivetune/blob/main/app/src/main/kotlin/moe/koiverse/archivetune/ui/component/Lyrics.kt"
click node_ai_text "https://github.com/inuhepott/archivetune/blob/main/app/src/main/kotlin/moe/koiverse/archivetune/ai/AiTextService.kt"
click node_recognition "https://github.com/inuhepott/archivetune/blob/main/app/src/main/kotlin/moe/koiverse/archivetune/musicrecognition/MusicRecognitionTileService.kt"
click node_statistics "https://github.com/inuhepott/archivetune/blob/main/app/src/main/kotlin/moe/koiverse/archivetune/ui/screens/StatsScreen.kt"
click node_social "https://github.com/inuhepott/archivetune/blob/main/app/src/main/kotlin/moe/koiverse/archivetune/utils/ScrobbleManager.kt"
click node_together "https://github.com/inuhepott/archivetune/tree/main/app/src/main/kotlin/moe/koiverse/archivetune/together"

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_app_ui,node_player_ui,node_main toneBlue
class node_youtube,node_metadata,node_local_scan toneAmber
class node_music_service,node_queues,node_audio,node_downloads toneMint
class node_lyrics_fetch,node_lyrics_preload,node_lyrics_ui,node_ai_text,node_recognition toneRose
class node_database,node_statistics,node_social,node_together,node_listener,node_youtube_api,node_external_services toneIndigo
```

## Components

### App experience

- [Browse and search](https://github.com/inuhepott/archivetune/tree/main/app/src/main/kotlin/moe/koiverse/archivetune/ui/screens): `app/src/main/kotlin/moe/koiverse/archivetune/ui/screens`
- [Player interface](https://github.com/inuhepott/archivetune/blob/main/app/src/main/kotlin/moe/koiverse/archivetune/ui/player/Player.kt): `app/src/main/kotlin/moe/koiverse/archivetune/ui/player/Player.kt`
- [App shell](https://github.com/inuhepott/archivetune/blob/main/app/src/main/kotlin/moe/koiverse/archivetune/MainActivity.kt): `app/src/main/kotlin/moe/koiverse/archivetune/MainActivity.kt`

### Music access

- [YouTube Music access](https://github.com/inuhepott/archivetune/tree/main/innertube/src/main/kotlin/moe/koiverse/archivetune/innertube): `innertube/src/main/kotlin/moe/koiverse/archivetune/innertube`
- [Track metadata](https://github.com/inuhepott/archivetune/blob/main/app/src/main/kotlin/moe/koiverse/archivetune/models/MediaMetadata.kt): `app/src/main/kotlin/moe/koiverse/archivetune/models/MediaMetadata.kt`
- [Local music scan](https://github.com/inuhepott/archivetune/blob/main/app/src/main/kotlin/moe/koiverse/archivetune/localmedia/LocalSongScanner.kt): `app/src/main/kotlin/moe/koiverse/archivetune/localmedia/LocalSongScanner.kt`

### Playback

- [Music service](https://github.com/inuhepott/archivetune/blob/main/app/src/main/kotlin/moe/koiverse/archivetune/playback/MusicService.kt): `app/src/main/kotlin/moe/koiverse/archivetune/playback/MusicService.kt`
- [Playback queues](https://github.com/inuhepott/archivetune/tree/main/app/src/main/kotlin/moe/koiverse/archivetune/playback/queues): `app/src/main/kotlin/moe/koiverse/archivetune/playback/queues`
- [Audio processing](https://github.com/inuhepott/archivetune/tree/main/app/src/main/kotlin/moe/koiverse/archivetune/playback): `app/src/main/kotlin/moe/koiverse/archivetune/playback`
- [Offline downloads](https://github.com/inuhepott/archivetune/blob/main/app/src/main/kotlin/moe/koiverse/archivetune/playback/ExoDownloadService.kt): `app/src/main/kotlin/moe/koiverse/archivetune/playback/ExoDownloadService.kt`

### Lyrics and discovery

- [Lyrics retrieval](https://github.com/inuhepott/archivetune/blob/main/app/src/main/kotlin/moe/koiverse/archivetune/lyrics/LyricsHelper.kt): `app/src/main/kotlin/moe/koiverse/archivetune/lyrics/LyricsHelper.kt`
- [Lyrics preloader](https://github.com/inuhepott/archivetune/blob/main/app/src/main/kotlin/moe/koiverse/archivetune/lyrics/LyricsPreloadManager.kt): `app/src/main/kotlin/moe/koiverse/archivetune/lyrics/LyricsPreloadManager.kt`
- [Synced lyrics](https://github.com/inuhepott/archivetune/blob/main/app/src/main/kotlin/moe/koiverse/archivetune/ui/component/Lyrics.kt): `app/src/main/kotlin/moe/koiverse/archivetune/ui/component/Lyrics.kt`
- [Lyrics translation](https://github.com/inuhepott/archivetune/blob/main/app/src/main/kotlin/moe/koiverse/archivetune/ai/AiTextService.kt): `app/src/main/kotlin/moe/koiverse/archivetune/ai/AiTextService.kt`
- [Music recognition](https://github.com/inuhepott/archivetune/blob/main/app/src/main/kotlin/moe/koiverse/archivetune/musicrecognition/MusicRecognitionTileService.kt): `app/src/main/kotlin/moe/koiverse/archivetune/musicrecognition/MusicRecognitionTileService.kt`

### Library and integrations

- [Music database](https://github.com/inuhepott/archivetune/blob/main/app/src/main/kotlin/moe/koiverse/archivetune/db/MusicDatabase.kt): `app/src/main/kotlin/moe/koiverse/archivetune/db/MusicDatabase.kt`
- [Listening statistics](https://github.com/inuhepott/archivetune/blob/main/app/src/main/kotlin/moe/koiverse/archivetune/ui/screens/StatsScreen.kt): `app/src/main/kotlin/moe/koiverse/archivetune/ui/screens/StatsScreen.kt`
- [Listening integrations](https://github.com/inuhepott/archivetune/blob/main/app/src/main/kotlin/moe/koiverse/archivetune/utils/ScrobbleManager.kt): `app/src/main/kotlin/moe/koiverse/archivetune/utils/ScrobbleManager.kt`
- [Shared listening](https://github.com/inuhepott/archivetune/tree/main/app/src/main/kotlin/moe/koiverse/archivetune/together): `app/src/main/kotlin/moe/koiverse/archivetune/together`

### Other components

- **Listener**
- **YouTube service**
- **External services**

## Connections

- Listener → App shell: opens (evidence: `README.md`)
- App shell → Browse and search: presents (evidence: `app/src/main/kotlin/moe/koiverse/archivetune/MainActivity.kt`)
- Listener → Browse and search: browses (evidence: `README.md`)
- Browse and search → YouTube Music access: requests catalog (evidence: `app/src/main/kotlin/moe/koiverse/archivetune/ui/screens/settings/StorageSettings.kt`)
- YouTube Music access → YouTube service: requests data
- YouTube Music access → Track metadata: maps results
- Local music scan → Music database: indexes songs
- Track metadata → Music service: supplies tracks (evidence: `app/src/main/kotlin/moe/koiverse/archivetune/playback/MusicService.kt`)
- Music service → YouTube Music access: uses (evidence: `app/src/main/kotlin/moe/koiverse/archivetune/playback/MusicService.kt`)
- Music service → Music database: reads and writes (evidence: `app/src/main/kotlin/moe/koiverse/archivetune/playback/MusicService.kt`)
- Music service → Lyrics preloader: preloads lyrics (evidence: `app/src/main/kotlin/moe/koiverse/archivetune/playback/MusicService.kt`)
- Music service → Playback queues: uses queue (evidence: `app/src/main/kotlin/moe/koiverse/archivetune/playback/MusicService.kt`)
- Music service → Audio processing: processes audio (evidence: `README.md`)
- Music service → Offline downloads: starts downloads (evidence: `app/src/main/kotlin/moe/koiverse/archivetune/playback/MusicService.kt`)
- Music service → Player interface: drives playback (evidence: `app/src/main/kotlin/moe/koiverse/archivetune/playback/MusicService.kt`)
- Lyrics preloader → Music database: checks and caches (evidence: `app/src/main/kotlin/moe/koiverse/archivetune/lyrics/LyricsPreloadManager.kt`)
- Lyrics preloader → Lyrics retrieval: fetches lyrics (evidence: `app/src/main/kotlin/moe/koiverse/archivetune/lyrics/LyricsPreloadManager.kt`)
- Lyrics retrieval → External services: queries providers
- Synced lyrics → Lyrics retrieval: displays lyrics
- Synced lyrics → Lyrics translation: translates text
- Music recognition → External services: identifies music
- Listening statistics → Music database: reads history
- Listening integrations → External services: syncs listening (evidence: `README.md`)
- Shared listening → External services: coordinates playback
- Listener → Synced lyrics: views lyrics (evidence: `README.md`)
- Listener → Music recognition: recognizes music (evidence: `README.md`)
- Listener → Listening statistics: reviews listening (evidence: `README.md`)
