# feeluown/fuoevolve architecture

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

- Interactive diagram: https://gitdiagram.com/feeluown/fuoevolve
- Repository: https://github.com/feeluown/fuoevolve

## Overview

FuoEvolve is a cross-platform music player combining online providers, local and downloaded music, playback, lyrics, and video. The principal workflow is to discover or search for a track, add it to playback, resolve a playable source, and play it through a platform engine. Other documented capabilities include provider accounts and libraries, local playlists, downloads, recognition, and synchronized lyrics. The tree and excerpts establish the major modules, but do not show most application wiring; uncertain connections are therefore omitted or marked unverified.

Main entry points: [`provider/api/src/commonMain/kotlin/org/feeluown/mobile/ProviderRepositoryContracts.kt`](https://github.com/feeluown/fuoevolve/blob/master/provider/api/src/commonMain/kotlin/org/feeluown/mobile/ProviderRepositoryContracts.kt) (Provider contracts), [`feature/playback/src/commonMain/kotlin/org/feeluown/mobile/PlaybackQueueController.kt`](https://github.com/feeluown/fuoevolve/blob/master/feature/playback/src/commonMain/kotlin/org/feeluown/mobile/PlaybackQueueController.kt) (Playback queue), [`feature/home/src/commonMain/kotlin/org/feeluown/mobile/feature/home/HomeFeature.kt`](https://github.com/feeluown/fuoevolve/blob/master/feature/home/src/commonMain/kotlin/org/feeluown/mobile/feature/home/HomeFeature.kt) (Home and discovery), [`feature/playback/src/commonMain/kotlin/org/feeluown/mobile/PlaybackStartCoordinator.kt`](https://github.com/feeluown/fuoevolve/blob/master/feature/playback/src/commonMain/kotlin/org/feeluown/mobile/PlaybackStartCoordinator.kt) (Playback start)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application hosts"]
  node_android["Android app<br/>[MainActivity.kt]"]
  node_desktop["Desktop app<br/>[NucleusMain.kt]"]
  node_ios["iOS app<br/>[ContentView.swift]"]
end

subgraph group_discovery["Discovery and providers"]
  node_home["Home and discovery<br/>[HomeFeature.kt]"]
  node_search["Search<br/>[SearchFeature.kt]"]
  node_provider_catalog["Provider catalog"]
  node_provider_auth["Provider accounts"]
  node_netease["NetEase provider<br/>[NeteaseProvider.kt]"]
  node_qqmusic["QQ Music provider<br/>[QQMusicProvider.kt]"]
  node_bilibili["Bilibili provider"]
  node_ytmusic["YouTube Music provider"]
  node_provider_api["Provider contracts"]
end

subgraph group_playback["Playback"]
  node_queue["Playback queue"]
  node_start["Playback start"]
  node_resolved["Resolved source"]
  node_session["Playback session<br/>[PlaybackSession.kt]"]
  node_android_engine["Android playback"]
  node_desktop_engine["Desktop playback"]
  node_ios_engine["iOS playback"]
  node_android_service["Android media service"]
  node_lyrics["Lyrics publishing"]
end

subgraph group_library["Music library"]
  node_recognition["Audio recognition"]
  node_local_music["Local music"]
  node_local_playlist["Local playlists"]
  node_downloads["Downloads<br/>[DownloadFeature.kt]"]
  node_android_download["Android download storage"]
  node_history[("Listening history")]
end

node_listener(("Listener"))

node_listener -.->|"uses"| node_android
node_listener -.->|"uses"| node_desktop
node_listener -.->|"uses"| node_ios
node_android -.->|"presents"| node_home
node_desktop -.->|"presents"| node_home
node_ios -.->|"presents"| node_home
node_home -.->|"browses"| node_provider_catalog
node_search -.->|"searches"| node_provider_api
node_provider_catalog -.->|"uses"| node_provider_api
node_provider_auth -.->|"authenticates"| node_provider_api
node_netease -.->|"implements"| node_provider_api
node_qqmusic -.->|"implements"| node_provider_api
node_bilibili -.->|"implements"| node_provider_api
node_ytmusic -.->|"implements"| node_provider_api
node_home -.->|"selects tracks"| node_queue
node_search -.->|"selects tracks"| node_queue
node_queue -->|"starts track"| node_start
node_start -.->|"resolves source"| node_provider_api
node_start -.->|"builds source"| node_resolved
node_android_engine -->|"connects controller"| node_android_service
node_android_service -.->|"publishes lyrics"| node_lyrics
node_local_music -.->|"selects tracks"| node_queue
node_local_playlist -.->|"selects tracks"| node_queue
node_downloads -.->|"stores files"| node_android_download
node_recognition -.->|"finds matches"| node_search
node_queue -.->|"records listening"| node_history

click node_android "https://github.com/feeluown/fuoevolve/blob/master/androidApp/src/main/kotlin/org/feeluown/mobile/MainActivity.kt"
click node_desktop "https://github.com/feeluown/fuoevolve/blob/master/desktopApp/src/main/kotlin/org/feeluown/mobile/nucleus/NucleusMain.kt"
click node_ios "https://github.com/feeluown/fuoevolve/blob/master/iosApp/FuoEvolve/ContentView.swift"
click node_home "https://github.com/feeluown/fuoevolve/blob/master/feature/home/src/commonMain/kotlin/org/feeluown/mobile/feature/home/HomeFeature.kt"
click node_search "https://github.com/feeluown/fuoevolve/blob/master/feature/search/src/commonMain/kotlin/org/feeluown/mobile/SearchFeature.kt"
click node_provider_catalog "https://github.com/feeluown/fuoevolve/blob/master/feature/providercatalog/src/commonMain/kotlin/org/feeluown/mobile/ProviderCatalogFeature.kt"
click node_provider_auth "https://github.com/feeluown/fuoevolve/blob/master/feature/providerauth/src/commonMain/kotlin/org/feeluown/mobile/ProviderAuthFeature.kt"
click node_netease "https://github.com/feeluown/fuoevolve/blob/master/provider/netease/src/commonMain/kotlin/org/feeluown/mobile/provider/netease/NeteaseProvider.kt"
click node_qqmusic "https://github.com/feeluown/fuoevolve/blob/master/provider/qqmusic/src/commonMain/kotlin/org/feeluown/mobile/provider/qqmusic/QQMusicProvider.kt"
click node_bilibili "https://github.com/feeluown/fuoevolve/blob/master/provider/bilibili/src/commonMain/kotlin/org/feeluown/mobile/provider/bilibili/BilibiliProvider.kt"
click node_ytmusic "https://github.com/feeluown/fuoevolve/blob/master/provider/ytmusic/src/commonMain/kotlin/org/feeluown/mobile/provider/ytmusic/YtMusicPlayerClients.kt"
click node_provider_api "https://github.com/feeluown/fuoevolve/blob/master/provider/api/src/commonMain/kotlin/org/feeluown/mobile/ProviderRepositoryContracts.kt"
click node_queue "https://github.com/feeluown/fuoevolve/blob/master/feature/playback/src/commonMain/kotlin/org/feeluown/mobile/PlaybackQueueController.kt"
click node_start "https://github.com/feeluown/fuoevolve/blob/master/feature/playback/src/commonMain/kotlin/org/feeluown/mobile/PlaybackStartCoordinator.kt"
click node_resolved "https://github.com/feeluown/fuoevolve/blob/master/feature/playback/src/commonMain/kotlin/org/feeluown/mobile/ResolvedPlaybackSource.kt"
click node_session "https://github.com/feeluown/fuoevolve/blob/master/playback/api/src/commonMain/kotlin/org/feeluown/mobile/playback/api/PlaybackSession.kt"
click node_android_engine "https://github.com/feeluown/fuoevolve/blob/master/androidApp/src/main/kotlin/org/feeluown/mobile/AndroidNativeAudioEngine.kt"
click node_desktop_engine "https://github.com/feeluown/fuoevolve/blob/master/desktopRuntime/src/main/kotlin/org/feeluown/mobile/desktop/DesktopMpvPlaybackEngine.kt"
click node_ios_engine "https://github.com/feeluown/fuoevolve/blob/master/shared/src/iosMain/kotlin/org/feeluown/mobile/IosNativeAudioEngine.kt"
click node_android_service "https://github.com/feeluown/fuoevolve/blob/master/androidApp/src/main/kotlin/org/feeluown/mobile/FuoPlaybackService.kt"
click node_lyrics "https://github.com/feeluown/fuoevolve/blob/master/androidApp/src/main/kotlin/org/feeluown/mobile/LyriconLyricsPublisher.kt"
click node_recognition "https://github.com/feeluown/fuoevolve/blob/master/feature/recognition/src/commonMain/kotlin/org/feeluown/mobile/AudioRecognitionController.kt"
click node_local_music "https://github.com/feeluown/fuoevolve/blob/master/feature/localmusic/src/commonMain/kotlin/org/feeluown/mobile/LocalMusicFeature.kt"
click node_local_playlist "https://github.com/feeluown/fuoevolve/blob/master/feature/localplaylist/src/commonMain/kotlin/org/feeluown/mobile/LocalPlaylistFeature.kt"
click node_downloads "https://github.com/feeluown/fuoevolve/blob/master/feature/download/src/commonMain/kotlin/org/feeluown/mobile/DownloadFeature.kt"
click node_android_download "https://github.com/feeluown/fuoevolve/blob/master/androidApp/src/main/kotlin/org/feeluown/mobile/AndroidDownloadRepository.kt"
click node_history "https://github.com/feeluown/fuoevolve/blob/master/persistence/listening/src/commonMain/kotlin/org/feeluown/mobile/persistence/listening/ListeningHistoryStore.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 toneBlue
class node_home,node_search,node_provider_catalog,node_provider_auth,node_netease,node_qqmusic,node_bilibili,node_ytmusic,node_provider_api toneAmber
class node_queue,node_start,node_resolved,node_session,node_android_engine,node_desktop_engine,node_ios_engine,node_android_service,node_lyrics toneMint
class node_recognition,node_local_music,node_local_playlist,node_downloads,node_android_download,node_history toneRose
class node_listener toneIndigo
```

## Components

### Application hosts

- [Android app](https://github.com/feeluown/fuoevolve/blob/master/androidApp/src/main/kotlin/org/feeluown/mobile/MainActivity.kt): `androidApp/src/main/kotlin/org/feeluown/mobile/MainActivity.kt`
- [Desktop app](https://github.com/feeluown/fuoevolve/blob/master/desktopApp/src/main/kotlin/org/feeluown/mobile/nucleus/NucleusMain.kt): `desktopApp/src/main/kotlin/org/feeluown/mobile/nucleus/NucleusMain.kt`
- [iOS app](https://github.com/feeluown/fuoevolve/blob/master/iosApp/FuoEvolve/ContentView.swift): `iosApp/FuoEvolve/ContentView.swift`

### Discovery and providers

- [Home and discovery](https://github.com/feeluown/fuoevolve/blob/master/feature/home/src/commonMain/kotlin/org/feeluown/mobile/feature/home/HomeFeature.kt): `feature/home/src/commonMain/kotlin/org/feeluown/mobile/feature/home/HomeFeature.kt`
- [Search](https://github.com/feeluown/fuoevolve/blob/master/feature/search/src/commonMain/kotlin/org/feeluown/mobile/SearchFeature.kt): `feature/search/src/commonMain/kotlin/org/feeluown/mobile/SearchFeature.kt`
- [Provider catalog](https://github.com/feeluown/fuoevolve/blob/master/feature/providercatalog/src/commonMain/kotlin/org/feeluown/mobile/ProviderCatalogFeature.kt): `feature/providercatalog/src/commonMain/kotlin/org/feeluown/mobile/ProviderCatalogFeature.kt`
- [Provider accounts](https://github.com/feeluown/fuoevolve/blob/master/feature/providerauth/src/commonMain/kotlin/org/feeluown/mobile/ProviderAuthFeature.kt): `feature/providerauth/src/commonMain/kotlin/org/feeluown/mobile/ProviderAuthFeature.kt`
- [NetEase provider](https://github.com/feeluown/fuoevolve/blob/master/provider/netease/src/commonMain/kotlin/org/feeluown/mobile/provider/netease/NeteaseProvider.kt): `provider/netease/src/commonMain/kotlin/org/feeluown/mobile/provider/netease/NeteaseProvider.kt`
- [QQ Music provider](https://github.com/feeluown/fuoevolve/blob/master/provider/qqmusic/src/commonMain/kotlin/org/feeluown/mobile/provider/qqmusic/QQMusicProvider.kt): `provider/qqmusic/src/commonMain/kotlin/org/feeluown/mobile/provider/qqmusic/QQMusicProvider.kt`
- [Bilibili provider](https://github.com/feeluown/fuoevolve/blob/master/provider/bilibili/src/commonMain/kotlin/org/feeluown/mobile/provider/bilibili/BilibiliProvider.kt): `provider/bilibili/src/commonMain/kotlin/org/feeluown/mobile/provider/bilibili/BilibiliProvider.kt`
- [YouTube Music provider](https://github.com/feeluown/fuoevolve/blob/master/provider/ytmusic/src/commonMain/kotlin/org/feeluown/mobile/provider/ytmusic/YtMusicPlayerClients.kt): `provider/ytmusic/src/commonMain/kotlin/org/feeluown/mobile/provider/ytmusic/YtMusicPlayerClients.kt`
- [Provider contracts](https://github.com/feeluown/fuoevolve/blob/master/provider/api/src/commonMain/kotlin/org/feeluown/mobile/ProviderRepositoryContracts.kt): `provider/api/src/commonMain/kotlin/org/feeluown/mobile/ProviderRepositoryContracts.kt`

### Playback

- [Playback queue](https://github.com/feeluown/fuoevolve/blob/master/feature/playback/src/commonMain/kotlin/org/feeluown/mobile/PlaybackQueueController.kt): `feature/playback/src/commonMain/kotlin/org/feeluown/mobile/PlaybackQueueController.kt`
- [Playback start](https://github.com/feeluown/fuoevolve/blob/master/feature/playback/src/commonMain/kotlin/org/feeluown/mobile/PlaybackStartCoordinator.kt): `feature/playback/src/commonMain/kotlin/org/feeluown/mobile/PlaybackStartCoordinator.kt`
- [Resolved source](https://github.com/feeluown/fuoevolve/blob/master/feature/playback/src/commonMain/kotlin/org/feeluown/mobile/ResolvedPlaybackSource.kt): `feature/playback/src/commonMain/kotlin/org/feeluown/mobile/ResolvedPlaybackSource.kt`
- [Playback session](https://github.com/feeluown/fuoevolve/blob/master/playback/api/src/commonMain/kotlin/org/feeluown/mobile/playback/api/PlaybackSession.kt): `playback/api/src/commonMain/kotlin/org/feeluown/mobile/playback/api/PlaybackSession.kt`
- [Android playback](https://github.com/feeluown/fuoevolve/blob/master/androidApp/src/main/kotlin/org/feeluown/mobile/AndroidNativeAudioEngine.kt): `androidApp/src/main/kotlin/org/feeluown/mobile/AndroidNativeAudioEngine.kt`
- [Desktop playback](https://github.com/feeluown/fuoevolve/blob/master/desktopRuntime/src/main/kotlin/org/feeluown/mobile/desktop/DesktopMpvPlaybackEngine.kt): `desktopRuntime/src/main/kotlin/org/feeluown/mobile/desktop/DesktopMpvPlaybackEngine.kt`
- [iOS playback](https://github.com/feeluown/fuoevolve/blob/master/shared/src/iosMain/kotlin/org/feeluown/mobile/IosNativeAudioEngine.kt): `shared/src/iosMain/kotlin/org/feeluown/mobile/IosNativeAudioEngine.kt`
- [Android media service](https://github.com/feeluown/fuoevolve/blob/master/androidApp/src/main/kotlin/org/feeluown/mobile/FuoPlaybackService.kt): `androidApp/src/main/kotlin/org/feeluown/mobile/FuoPlaybackService.kt`
- [Lyrics publishing](https://github.com/feeluown/fuoevolve/blob/master/androidApp/src/main/kotlin/org/feeluown/mobile/LyriconLyricsPublisher.kt): `androidApp/src/main/kotlin/org/feeluown/mobile/LyriconLyricsPublisher.kt`

### Music library

- [Audio recognition](https://github.com/feeluown/fuoevolve/blob/master/feature/recognition/src/commonMain/kotlin/org/feeluown/mobile/AudioRecognitionController.kt): `feature/recognition/src/commonMain/kotlin/org/feeluown/mobile/AudioRecognitionController.kt`
- [Local music](https://github.com/feeluown/fuoevolve/blob/master/feature/localmusic/src/commonMain/kotlin/org/feeluown/mobile/LocalMusicFeature.kt): `feature/localmusic/src/commonMain/kotlin/org/feeluown/mobile/LocalMusicFeature.kt`
- [Local playlists](https://github.com/feeluown/fuoevolve/blob/master/feature/localplaylist/src/commonMain/kotlin/org/feeluown/mobile/LocalPlaylistFeature.kt): `feature/localplaylist/src/commonMain/kotlin/org/feeluown/mobile/LocalPlaylistFeature.kt`
- [Downloads](https://github.com/feeluown/fuoevolve/blob/master/feature/download/src/commonMain/kotlin/org/feeluown/mobile/DownloadFeature.kt): `feature/download/src/commonMain/kotlin/org/feeluown/mobile/DownloadFeature.kt`
- [Android download storage](https://github.com/feeluown/fuoevolve/blob/master/androidApp/src/main/kotlin/org/feeluown/mobile/AndroidDownloadRepository.kt): `androidApp/src/main/kotlin/org/feeluown/mobile/AndroidDownloadRepository.kt`
- [Listening history](https://github.com/feeluown/fuoevolve/blob/master/persistence/listening/src/commonMain/kotlin/org/feeluown/mobile/persistence/listening/ListeningHistoryStore.kt): `persistence/listening/src/commonMain/kotlin/org/feeluown/mobile/persistence/listening/ListeningHistoryStore.kt`

### Other components

- **Listener**

## Connections

- Listener → Android app: uses
- Listener → Desktop app: uses
- Listener → iOS app: uses
- Android app → Home and discovery: presents
- Desktop app → Home and discovery: presents
- iOS app → Home and discovery: presents
- Home and discovery → Provider catalog: browses
- Search → Provider contracts: searches
- Provider catalog → Provider contracts: uses
- Provider accounts → Provider contracts: authenticates
- NetEase provider → Provider contracts: implements
- QQ Music provider → Provider contracts: implements
- Bilibili provider → Provider contracts: implements
- YouTube Music provider → Provider contracts: implements
- Home and discovery → Playback queue: selects tracks
- Search → Playback queue: selects tracks
- Playback queue → Playback start: starts track (evidence: `feature/playback/src/commonMain/kotlin/org/feeluown/mobile/PlaybackStartCoordinator.kt`)
- Playback start → Provider contracts: resolves source
- Playback start → Resolved source: builds source
- Android playback → Android media service: connects controller (evidence: `androidApp/src/main/kotlin/org/feeluown/mobile/AndroidNativeAudioEngine.kt`)
- Android media service → Lyrics publishing: publishes lyrics
- Local music → Playback queue: selects tracks
- Local playlists → Playback queue: selects tracks
- Downloads → Android download storage: stores files
- Audio recognition → Search: finds matches
- Playback queue → Listening history: records listening
