# taotaomusic/core architecture

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

- Interactive diagram: https://gitdiagram.com/taotaomusic/core
- Repository: https://github.com/taotaomusic/core

## Overview

桃桃音乐 is a cross-platform music player backed by a self-hosted API. The main workflow is search, enqueue a persistent placeholder, resolve a playable CDN URL on demand, then stream audio directly from the CDN. Android playback and API calls are represented from the README and sampled service; server-side search ownership is supported by the sampled controller, while other documented product branches use their tree paths. The excerpts do not establish every client-to-server call, so uncertain wiring is omitted.

Main entry points: [`androidApp/src/main/java/com/taotao/music/data/TencentMusicApi.kt`](https://github.com/taotaomusic/core/blob/main/androidApp/src/main/java/com/taotao/music/data/TencentMusicApi.kt) (Android API), [`androidApp/src/main/java/com/taotao/music/ui/app/AppContent.kt`](https://github.com/taotaomusic/core/blob/main/androidApp/src/main/java/com/taotao/music/ui/app/AppContent.kt) (Android app), [`server/src/upstream/music-source.registry.ts`](https://github.com/taotaomusic/core/blob/main/server/src/upstream/music-source.registry.ts) (Music sources), [`server/src/database/database.service.ts`](https://github.com/taotaomusic/core/blob/main/server/src/database/database.service.ts) (PostgreSQL)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Music clients"]
  node_android["Android app<br/>[AppContent.kt]"]
  node_android_api["Android API<br/>[TencentMusicApi.kt]"]
  node_android_player["Android playback<br/>[PlaybackService.kt]"]
  node_desktop["Windows app<br/>[DesktopShell.kt]"]
  node_web["Web share player<br/>[Main.kt]"]
  node_shared_ui["Shared player UI<br/>[PlayerSurface.kt]"]
end

subgraph group_music["Music services"]
  node_api["Music API"]
  node_search["Search service<br/>[search.service.ts]"]
  node_sources["Music sources"]
end

subgraph group_accounts["Accounts and library"]
  node_auth["User authentication<br/>[auth.controller.ts]"]
  node_favorites["Favorites"]
  node_playlists["Cloud playlists"]
  node_history["Playback history"]
  node_database[("PostgreSQL")]
end

subgraph group_platform["Sharing and releases"]
  node_im["Messaging<br/>[im.controller.ts]"]
  node_ai["AI image generation"]
  node_sharing["Song sharing"]
  node_releases["App and desktop releases"]
  node_desktop_releases["Desktop release service"]
end

subgraph group_admin["Administration"]
  node_admin_ui["Admin console<br/>[App.vue]"]
  node_admin_auth["Admin authentication"]
  node_source_admin["Source management"]
  node_release_admin["Release management"]
end

node_listener(("Listener"))
node_cdn(("Music CDN"))

node_listener -->|"uses"| node_android
node_listener -->|"uses"| node_desktop
node_listener -->|"opens share"| node_web
node_android -->|"requests music"| node_android_api
node_android -->|"controls playback"| node_android_player
node_android_player -->|"resolves placeholder"| node_android_api
node_android_player -->|"streams audio"| node_cdn
node_desktop -->|"uses interface"| node_shared_ui
node_android -->|"uses interface"| node_shared_ui
node_web -->|"uses interface"| node_shared_ui
node_android_api -->|"requests"| node_api
node_api -->|"searches"| node_search
node_search -->|"queries sources"| node_sources
node_api -->|"resolves song"| node_sources
node_sources -->|"returns stream URL"| node_cdn
node_android_api -->|"authenticates"| node_auth
node_android_api -->|"manages favorites"| node_favorites
node_android_api -->|"manages playlists"| node_playlists
node_android_api -->|"syncs playback"| node_history
node_auth -->|"reads and writes"| node_database
node_favorites -->|"reads and writes"| node_database
node_playlists -->|"reads and writes"| node_database
node_history -->|"reads and writes"| node_database
node_android_api -.->|"uses messaging"| node_im
node_android_api -.->|"requests image generation"| node_ai
node_web -->|"loads shared song"| node_sharing
node_desktop -.->|"checks updates"| node_desktop_releases
node_android_api -.->|"checks updates"| node_releases
node_admin_ui -->|"authenticates"| node_admin_auth
node_admin_ui -->|"manages sources"| node_source_admin
node_admin_ui -->|"manages releases"| node_release_admin
node_release_admin -->|"publishes releases"| node_releases
node_source_admin -->|"configures sources"| node_sources

click node_android "https://github.com/taotaomusic/core/blob/main/androidApp/src/main/java/com/taotao/music/ui/app/AppContent.kt"
click node_android_api "https://github.com/taotaomusic/core/blob/main/androidApp/src/main/java/com/taotao/music/data/TencentMusicApi.kt"
click node_android_player "https://github.com/taotaomusic/core/blob/main/androidApp/src/main/java/com/taotao/music/player/PlaybackService.kt"
click node_desktop "https://github.com/taotaomusic/core/blob/main/desktopApp/src/main/kotlin/com/taotao/music/desktop/DesktopShell.kt"
click node_web "https://github.com/taotaomusic/core/blob/main/webApp/src/wasmJsMain/kotlin/com/taotao/music/web/Main.kt"
click node_shared_ui "https://github.com/taotaomusic/core/blob/main/player-ui/src/commonMain/kotlin/com/taotao/music/playerui/PlayerSurface.kt"
click node_api "https://github.com/taotaomusic/core/blob/main/server/src/music/music.controller.ts"
click node_search "https://github.com/taotaomusic/core/blob/main/server/src/music/search.service.ts"
click node_sources "https://github.com/taotaomusic/core/blob/main/server/src/upstream/music-source.registry.ts"
click node_auth "https://github.com/taotaomusic/core/blob/main/server/src/auth/auth.controller.ts"
click node_favorites "https://github.com/taotaomusic/core/blob/main/server/src/favorites/favorites.controller.ts"
click node_playlists "https://github.com/taotaomusic/core/blob/main/server/src/playlists/playlists.controller.ts"
click node_history "https://github.com/taotaomusic/core/blob/main/server/src/playback/playback.controller.ts"
click node_database "https://github.com/taotaomusic/core/blob/main/server/src/database/database.service.ts"
click node_im "https://github.com/taotaomusic/core/blob/main/server/src/im/im.controller.ts"
click node_ai "https://github.com/taotaomusic/core/blob/main/server/src/image-generation/image-generation.controller.ts"
click node_sharing "https://github.com/taotaomusic/core/blob/main/server/src/shares/song-share.controller.ts"
click node_releases "https://github.com/taotaomusic/core/blob/main/server/src/release/release.controller.ts"
click node_desktop_releases "https://github.com/taotaomusic/core/blob/main/server/src/desktop-release/desktop-release.controller.ts"
click node_admin_ui "https://github.com/taotaomusic/core/blob/main/server/src/frontend/src/App.vue"
click node_admin_auth "https://github.com/taotaomusic/core/blob/main/server/src/admin-auth/admin-auth.controller.ts"
click node_source_admin "https://github.com/taotaomusic/core/blob/main/server/src/upstream/music-source-admin.controller.ts"
click node_release_admin "https://github.com/taotaomusic/core/blob/main/server/src/release/release-admin.controller.ts"

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_android_api,node_android_player,node_desktop,node_web,node_shared_ui toneBlue
class node_api,node_search,node_sources toneAmber
class node_auth,node_favorites,node_playlists,node_history,node_database toneMint
class node_im,node_ai,node_sharing,node_releases,node_desktop_releases toneRose
class node_admin_ui,node_admin_auth,node_source_admin,node_release_admin,node_listener,node_cdn toneIndigo
```

## Components

### Music clients

- [Android app](https://github.com/taotaomusic/core/blob/main/androidApp/src/main/java/com/taotao/music/ui/app/AppContent.kt): `androidApp/src/main/java/com/taotao/music/ui/app/AppContent.kt`
- [Android API](https://github.com/taotaomusic/core/blob/main/androidApp/src/main/java/com/taotao/music/data/TencentMusicApi.kt): `androidApp/src/main/java/com/taotao/music/data/TencentMusicApi.kt`
- [Android playback](https://github.com/taotaomusic/core/blob/main/androidApp/src/main/java/com/taotao/music/player/PlaybackService.kt): `androidApp/src/main/java/com/taotao/music/player/PlaybackService.kt`
- [Windows app](https://github.com/taotaomusic/core/blob/main/desktopApp/src/main/kotlin/com/taotao/music/desktop/DesktopShell.kt): `desktopApp/src/main/kotlin/com/taotao/music/desktop/DesktopShell.kt`
- [Web share player](https://github.com/taotaomusic/core/blob/main/webApp/src/wasmJsMain/kotlin/com/taotao/music/web/Main.kt): `webApp/src/wasmJsMain/kotlin/com/taotao/music/web/Main.kt`
- [Shared player UI](https://github.com/taotaomusic/core/blob/main/player-ui/src/commonMain/kotlin/com/taotao/music/playerui/PlayerSurface.kt): `player-ui/src/commonMain/kotlin/com/taotao/music/playerui/PlayerSurface.kt`

### Music services

- [Music API](https://github.com/taotaomusic/core/blob/main/server/src/music/music.controller.ts): `server/src/music/music.controller.ts`
- [Search service](https://github.com/taotaomusic/core/blob/main/server/src/music/search.service.ts): `server/src/music/search.service.ts`
- [Music sources](https://github.com/taotaomusic/core/blob/main/server/src/upstream/music-source.registry.ts): `server/src/upstream/music-source.registry.ts`

### Accounts and library

- [User authentication](https://github.com/taotaomusic/core/blob/main/server/src/auth/auth.controller.ts): `server/src/auth/auth.controller.ts`
- [Favorites](https://github.com/taotaomusic/core/blob/main/server/src/favorites/favorites.controller.ts): `server/src/favorites/favorites.controller.ts`
- [Cloud playlists](https://github.com/taotaomusic/core/blob/main/server/src/playlists/playlists.controller.ts): `server/src/playlists/playlists.controller.ts`
- [Playback history](https://github.com/taotaomusic/core/blob/main/server/src/playback/playback.controller.ts): `server/src/playback/playback.controller.ts`
- [PostgreSQL](https://github.com/taotaomusic/core/blob/main/server/src/database/database.service.ts): `server/src/database/database.service.ts`

### Sharing and releases

- [Messaging](https://github.com/taotaomusic/core/blob/main/server/src/im/im.controller.ts): `server/src/im/im.controller.ts`
- [AI image generation](https://github.com/taotaomusic/core/blob/main/server/src/image-generation/image-generation.controller.ts): `server/src/image-generation/image-generation.controller.ts`
- [Song sharing](https://github.com/taotaomusic/core/blob/main/server/src/shares/song-share.controller.ts): `server/src/shares/song-share.controller.ts`
- [App and desktop releases](https://github.com/taotaomusic/core/blob/main/server/src/release/release.controller.ts): `server/src/release/release.controller.ts`
- [Desktop release service](https://github.com/taotaomusic/core/blob/main/server/src/desktop-release/desktop-release.controller.ts): `server/src/desktop-release/desktop-release.controller.ts`

### Administration

- [Admin console](https://github.com/taotaomusic/core/blob/main/server/src/frontend/src/App.vue): `server/src/frontend/src/App.vue`
- [Admin authentication](https://github.com/taotaomusic/core/blob/main/server/src/admin-auth/admin-auth.controller.ts): `server/src/admin-auth/admin-auth.controller.ts`
- [Source management](https://github.com/taotaomusic/core/blob/main/server/src/upstream/music-source-admin.controller.ts): `server/src/upstream/music-source-admin.controller.ts`
- [Release management](https://github.com/taotaomusic/core/blob/main/server/src/release/release-admin.controller.ts): `server/src/release/release-admin.controller.ts`

### Other components

- **Listener**
- **Music CDN**

## Connections

- Listener → Android app: uses
- Listener → Windows app: uses
- Listener → Web share player: opens share
- Android app → Android API: requests music
- Android app → Android playback: controls playback
- Android playback → Android API: resolves placeholder
- Android playback → Music CDN: streams audio
- Windows app → Shared player UI: uses interface
- Android app → Shared player UI: uses interface
- Web share player → Shared player UI: uses interface
- Android API → Music API: requests
- Music API → Search service: searches
- Search service → Music sources: queries sources
- Music API → Music sources: resolves song
- Music sources → Music CDN: returns stream URL
- Android API → User authentication: authenticates
- Android API → Favorites: manages favorites
- Android API → Cloud playlists: manages playlists
- Android API → Playback history: syncs playback
- User authentication → PostgreSQL: reads and writes
- Favorites → PostgreSQL: reads and writes
- Cloud playlists → PostgreSQL: reads and writes
- Playback history → PostgreSQL: reads and writes
- Android API → Messaging: uses messaging
- Android API → AI image generation: requests image generation
- Web share player → Song sharing: loads shared song
- Windows app → Desktop release service: checks updates
- Android API → App and desktop releases: checks updates
- Admin console → Admin authentication: authenticates
- Admin console → Source management: manages sources
- Admin console → Release management: manages releases
- Release management → App and desktop releases: publishes releases
- Source management → Music sources: configures sources