# mrdsp18/notune architecture

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

- Interactive diagram: https://gitdiagram.com/mrdsp18/notune
- Repository: https://github.com/mrdsp18/notune

## Overview

NØTUNE is an Android music player and social music ecosystem. The main user path starts in the app, reaches the playback service, and uses YouTube Music for streaming; users can also search, download or play local music, and use AI and social features. The graph preserves documented capability branches and major indexed modules. Several subsystems are represented at directory level because their source was not sampled; their internal links are omitted where evidence was unavailable.

Main entry points: [`app/src/main/kotlin/com/music/echo/notune/flow/FlowEngine.kt`](https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/notune/flow/FlowEngine.kt) (Music flow), [`app/src/main/kotlin/com/music/echo/MainActivity.kt`](https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/MainActivity.kt) (Android app), [`app/src/main/kotlin/com/music/echo/playback/MusicService.kt`](https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/playback/MusicService.kt) (Playback service), [`app/src/main/kotlin/com/music/echo/recognition/MusicRecognitionService.kt`](https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/recognition/MusicRecognitionService.kt) (Song recognition)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and playback"]
  node_app["Android app<br/>[MainActivity.kt]"]
  node_player["Playback service<br/>[MusicService.kt]"]
  node_playerui["Player interface<br/>[Player.kt]"]
end

subgraph group_music["Music sources"]
  node_database[("Music database<br/>[MusicDatabase.kt]")]
  node_dao["Library data access<br/>[DatabaseDao.kt]"]
  node_metadata["Media metadata<br/>[MediaMetadata.kt]"]
  node_youtube["YouTube Music<br/>[YouTube.kt]"]
  node_youtubeclient["YouTube client<br/>[YouTubeClient.kt]"]
  node_downloads["Offline downloads"]
  node_localmedia["Local music"]
end

subgraph group_intelligence["AI and discovery"]
  node_search["AI music assistant<br/>[AiEngine.kt]"]
  node_flow["Music flow<br/>[FlowEngine.kt]"]
  node_flowcandidates["Flow candidates"]
  node_flowfilter["Candidate filtering"]
  node_flowscore["Candidate scoring"]
  node_flowqueue["Queue optimization"]
  node_musiccontext["Music context"]
  node_taste["Taste profiles"]
  node_recognition["Song recognition"]
  node_resampler["Audio resampling<br/>[AudioResampler.kt]"]
  node_signature["Vibra signatures<br/>[VibraSignature.kt]"]
  node_recognitionui["Recognition launcher"]
end

subgraph group_social["Social listening"]
  node_listen["Listen Together"]
  node_rooms["Listening rooms"]
  node_social["Social music"]
end

subgraph group_platform["Supporting services"]
  node_lyrics["Lyrics services"]
  node_secure["Secure credentials"]
  node_theme["Custom themes"]
  node_backend["NØTUNE backend<br/>[server.js]"]
end

node_listener(("Listener"))

node_listener -->|"opens"| node_app
node_app -->|"starts"| node_player
node_app -->|"joins rooms"| node_listen
node_app -.->|"presents"| node_playerui
node_player -->|"requests streams"| node_youtube
node_youtube -.->|"uses client"| node_youtubeclient
node_player -->|"reads and writes"| node_database
node_database -->|"exposes queries"| node_dao
node_listener -->|"asks for music"| node_search
node_listener -.->|"starts discovery"| node_flow
node_flow -->|"generates candidates"| node_flowcandidates
node_flow -->|"filters candidates"| node_flowfilter
node_flow -->|"scores candidates"| node_flowscore
node_flow -->|"optimizes queue"| node_flowqueue
node_musiccontext -->|"reads taste"| node_taste
node_recognitionui -->|"starts recognition"| node_recognition
node_recognition -->|"resamples audio"| node_resampler
node_recognition -->|"generates signatures"| node_signature
node_listener -->|"downloads music"| node_downloads
node_listener -->|"plays local music"| node_localmedia
node_listener -.->|"uses lyrics"| node_lyrics
node_listener -.->|"joins rooms"| node_rooms
node_listener -.->|"uses social features"| node_social
node_listener -->|"customizes appearance"| node_theme
node_listener -->|"stores credentials"| node_secure
node_search -.->|"uses service"| node_backend

click node_app "https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/MainActivity.kt"
click node_player "https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/playback/MusicService.kt"
click node_playerui "https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/ui/player/Player.kt"
click node_database "https://github.com/mrdsp18/notune/blob/main/core/src/main/kotlin/echo/music/iad1tya/db/MusicDatabase.kt"
click node_dao "https://github.com/mrdsp18/notune/blob/main/core/src/main/kotlin/echo/music/iad1tya/db/DatabaseDao.kt"
click node_metadata "https://github.com/mrdsp18/notune/blob/main/core/src/main/kotlin/echo/music/iad1tya/models/MediaMetadata.kt"
click node_youtube "https://github.com/mrdsp18/notune/blob/main/innertube/src/main/kotlin/com/music/innertube/YouTube.kt"
click node_youtubeclient "https://github.com/mrdsp18/notune/blob/main/innertube/src/main/kotlin/com/music/innertube/models/YouTubeClient.kt"
click node_downloads "https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/playback/ExoDownloadService.kt"
click node_localmedia "https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/localmedia/LocalSongScanner.kt"
click node_search "https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/notune/ai/AiEngine.kt"
click node_flow "https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/notune/flow/FlowEngine.kt"
click node_flowcandidates "https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/notune/flow/FlowCandidateGenerator.kt"
click node_flowfilter "https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/notune/flow/FlowCandidateFilter.kt"
click node_flowscore "https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/notune/flow/FlowCandidateScorer.kt"
click node_flowqueue "https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/notune/flow/FlowQueueOptimizer.kt"
click node_musiccontext "https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/notune/ai/MusicContextEngine.kt"
click node_taste "https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/notune/personalization/repository/TasteProfileRepository.kt"
click node_recognition "https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/recognition/MusicRecognitionService.kt"
click node_resampler "https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/recognition/AudioResampler.kt"
click node_signature "https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/recognition/VibraSignature.kt"
click node_recognitionui "https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/recognition/RecognitionForegroundService.kt"
click node_listen "https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/listentogether/ListenTogetherManager.kt"
click node_rooms "https://github.com/mrdsp18/notune/tree/main/app/src/main/kotlin/com/music/echo/notune/rooms"
click node_social "https://github.com/mrdsp18/notune/tree/main/app/src/main/kotlin/com/music/echo/notune/social"
click node_lyrics "https://github.com/mrdsp18/notune/tree/main/lyrics/src/main/kotlin/echo/music/iad1tya/api"
click node_secure "https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/notune/privacy/security/SecureStorageManager.kt"
click node_theme "https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/notune/theme/NoTuneThemeEngine.kt"
click node_backend "https://github.com/mrdsp18/notune/blob/main/notune-backend/server.js"

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,node_player,node_playerui toneBlue
class node_database,node_dao,node_metadata,node_youtube,node_youtubeclient,node_downloads,node_localmedia toneAmber
class node_search,node_flow,node_flowcandidates,node_flowfilter,node_flowscore,node_flowqueue,node_musiccontext,node_taste,node_recognition,node_resampler,node_signature,node_recognitionui toneMint
class node_listen,node_rooms,node_social toneRose
class node_lyrics,node_secure,node_theme,node_backend,node_listener toneIndigo
```

## Components

### App and playback

- [Android app](https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/MainActivity.kt): `app/src/main/kotlin/com/music/echo/MainActivity.kt`
- [Playback service](https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/playback/MusicService.kt): `app/src/main/kotlin/com/music/echo/playback/MusicService.kt`
- [Player interface](https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/ui/player/Player.kt): `app/src/main/kotlin/com/music/echo/ui/player/Player.kt`

### Music sources

- [Music database](https://github.com/mrdsp18/notune/blob/main/core/src/main/kotlin/echo/music/iad1tya/db/MusicDatabase.kt): `core/src/main/kotlin/echo/music/iad1tya/db/MusicDatabase.kt`
- [Library data access](https://github.com/mrdsp18/notune/blob/main/core/src/main/kotlin/echo/music/iad1tya/db/DatabaseDao.kt): `core/src/main/kotlin/echo/music/iad1tya/db/DatabaseDao.kt`
- [Media metadata](https://github.com/mrdsp18/notune/blob/main/core/src/main/kotlin/echo/music/iad1tya/models/MediaMetadata.kt): `core/src/main/kotlin/echo/music/iad1tya/models/MediaMetadata.kt`
- [YouTube Music](https://github.com/mrdsp18/notune/blob/main/innertube/src/main/kotlin/com/music/innertube/YouTube.kt): `innertube/src/main/kotlin/com/music/innertube/YouTube.kt`
- [YouTube client](https://github.com/mrdsp18/notune/blob/main/innertube/src/main/kotlin/com/music/innertube/models/YouTubeClient.kt): `innertube/src/main/kotlin/com/music/innertube/models/YouTubeClient.kt`
- [Offline downloads](https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/playback/ExoDownloadService.kt): `app/src/main/kotlin/com/music/echo/playback/ExoDownloadService.kt`
- [Local music](https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/localmedia/LocalSongScanner.kt): `app/src/main/kotlin/com/music/echo/localmedia/LocalSongScanner.kt`

### AI and discovery

- [AI music assistant](https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/notune/ai/AiEngine.kt): `app/src/main/kotlin/com/music/echo/notune/ai/AiEngine.kt`
- [Music flow](https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/notune/flow/FlowEngine.kt): `app/src/main/kotlin/com/music/echo/notune/flow/FlowEngine.kt`
- [Flow candidates](https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/notune/flow/FlowCandidateGenerator.kt): `app/src/main/kotlin/com/music/echo/notune/flow/FlowCandidateGenerator.kt`
- [Candidate filtering](https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/notune/flow/FlowCandidateFilter.kt): `app/src/main/kotlin/com/music/echo/notune/flow/FlowCandidateFilter.kt`
- [Candidate scoring](https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/notune/flow/FlowCandidateScorer.kt): `app/src/main/kotlin/com/music/echo/notune/flow/FlowCandidateScorer.kt`
- [Queue optimization](https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/notune/flow/FlowQueueOptimizer.kt): `app/src/main/kotlin/com/music/echo/notune/flow/FlowQueueOptimizer.kt`
- [Music context](https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/notune/ai/MusicContextEngine.kt): `app/src/main/kotlin/com/music/echo/notune/ai/MusicContextEngine.kt`
- [Taste profiles](https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/notune/personalization/repository/TasteProfileRepository.kt): `app/src/main/kotlin/com/music/echo/notune/personalization/repository/TasteProfileRepository.kt`
- [Song recognition](https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/recognition/MusicRecognitionService.kt): `app/src/main/kotlin/com/music/echo/recognition/MusicRecognitionService.kt`
- [Audio resampling](https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/recognition/AudioResampler.kt): `app/src/main/kotlin/com/music/echo/recognition/AudioResampler.kt`
- [Vibra signatures](https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/recognition/VibraSignature.kt): `app/src/main/kotlin/com/music/echo/recognition/VibraSignature.kt`
- [Recognition launcher](https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/recognition/RecognitionForegroundService.kt): `app/src/main/kotlin/com/music/echo/recognition/RecognitionForegroundService.kt`

### Social listening

- [Listen Together](https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/listentogether/ListenTogetherManager.kt): `app/src/main/kotlin/com/music/echo/listentogether/ListenTogetherManager.kt`
- [Listening rooms](https://github.com/mrdsp18/notune/tree/main/app/src/main/kotlin/com/music/echo/notune/rooms): `app/src/main/kotlin/com/music/echo/notune/rooms`
- [Social music](https://github.com/mrdsp18/notune/tree/main/app/src/main/kotlin/com/music/echo/notune/social): `app/src/main/kotlin/com/music/echo/notune/social`

### Supporting services

- [Lyrics services](https://github.com/mrdsp18/notune/tree/main/lyrics/src/main/kotlin/echo/music/iad1tya/api): `lyrics/src/main/kotlin/echo/music/iad1tya/api`
- [Secure credentials](https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/notune/privacy/security/SecureStorageManager.kt): `app/src/main/kotlin/com/music/echo/notune/privacy/security/SecureStorageManager.kt`
- [Custom themes](https://github.com/mrdsp18/notune/blob/main/app/src/main/kotlin/com/music/echo/notune/theme/NoTuneThemeEngine.kt): `app/src/main/kotlin/com/music/echo/notune/theme/NoTuneThemeEngine.kt`
- [NØTUNE backend](https://github.com/mrdsp18/notune/blob/main/notune-backend/server.js): `notune-backend/server.js`

### Other components

- **Listener**

## Connections

- Listener → Android app: opens
- Android app → Playback service: starts (evidence: `app/src/main/kotlin/com/music/echo/MainActivity.kt`)
- Android app → Listen Together: joins rooms (evidence: `app/src/main/kotlin/com/music/echo/MainActivity.kt`)
- Android app → Player interface: presents (evidence: `app/src/main/kotlin/com/music/echo/MainActivity.kt`)
- Playback service → YouTube Music: requests streams (evidence: `app/src/main/kotlin/com/music/echo/playback/MusicService.kt`)
- YouTube Music → YouTube client: uses client
- Playback service → Music database: reads and writes (evidence: `app/src/main/kotlin/com/music/echo/playback/MusicService.kt`)
- Music database → Library data access: exposes queries (evidence: `core/src/main/kotlin/echo/music/iad1tya/db/MusicDatabase.kt`)
- Listener → AI music assistant: asks for music
- Listener → Music flow: starts discovery
- Music flow → Flow candidates: generates candidates (evidence: `app/src/main/kotlin/com/music/echo/notune/flow/FlowEngine.kt`)
- Music flow → Candidate filtering: filters candidates (evidence: `app/src/main/kotlin/com/music/echo/notune/flow/FlowEngine.kt`)
- Music flow → Candidate scoring: scores candidates (evidence: `app/src/main/kotlin/com/music/echo/notune/flow/FlowEngine.kt`)
- Music flow → Queue optimization: optimizes queue (evidence: `app/src/main/kotlin/com/music/echo/notune/flow/FlowEngine.kt`)
- Music context → Taste profiles: reads taste (evidence: `app/src/main/kotlin/com/music/echo/notune/ai/MusicContextEngine.kt`)
- Recognition launcher → Song recognition: starts recognition (evidence: `app/src/main/kotlin/com/music/echo/recognition/RecognitionForegroundService.kt`)
- Song recognition → Audio resampling: resamples audio (evidence: `app/src/main/kotlin/com/music/echo/recognition/MusicRecognitionService.kt`)
- Song recognition → Vibra signatures: generates signatures (evidence: `app/src/main/kotlin/com/music/echo/recognition/MusicRecognitionService.kt`)
- Listener → Offline downloads: downloads music
- Listener → Local music: plays local music
- Listener → Lyrics services: uses lyrics
- Listener → Listening rooms: joins rooms
- Listener → Social music: uses social features
- Listener → Custom themes: customizes appearance
- Listener → Secure credentials: stores credentials
- AI music assistant → NØTUNE backend: uses service
