# zzyoxml/md3music architecture

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

- Interactive diagram: https://gitdiagram.com/zzyoxml/md3music
- Repository: https://github.com/zzyoxml/md3music

## Overview

MD3Music is an Android music player whose Flutter UI uses an embedded Rust HTTP API server to provide online Kugou music services, alongside local-library playback and native Android audio, lyric, and device integrations. The main online workflow is user discovery/search in Flutter, request handling by the local Rust server, and forwarding to Kugou; playback then uses the app’s playback stack. README capabilities are represented at subsystem level. Flutter source was not included, so UI-to-module wiring is summarized rather than inferred in detail.

Main entry points: [`lib`](https://github.com/zzyoxml/md3music/tree/rust-local-force/lib) (Flutter application), [`android/app/src/main/kotlin/com/md3music/md3music/AudioPlaybackService.kt`](https://github.com/zzyoxml/md3music/blob/rust-local-force/android/app/src/main/kotlin/com/md3music/md3music/AudioPlaybackService.kt) (Audio playback service), [`lib/modules`](https://github.com/zzyoxml/md3music/tree/rust-local-force/lib/modules) (Online music), [`lib/modules/library`](https://github.com/zzyoxml/md3music/tree/rust-local-force/lib/modules/library) (Local library)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Flutter app"]
  node_flutter["Flutter application"]
  node_online["Online music"]
  node_local["Local library"]
  node_user_features["User features"]
  node_settings["Settings and themes"]
end

subgraph group_api["Embedded API"]
  node_kugou_bridge["API server bridge<br/>[KugouApiService.kt]"]
  node_rust_server["HTTP server<br/>[server.rs]"]
  node_api_modules["Kugou endpoints"]
  node_request_layer["Request handling<br/>[request.rs]"]
  node_api_cache[("Response cache<br/>[cache.rs]")]
end

subgraph group_playback["Playback and audio"]
  node_playback_core["Audio playback service"]
  node_session["Media session"]
  node_audio_effects["Audio processing"]
  node_usb_native["USB audio output"]
end

subgraph group_experience["Lyrics and surfaces"]
  node_lyrics["Lyric experiences"]
  node_floating_lyrics["Floating lyrics"]
  node_recognition["Floating recognition"]
  node_widgets["Home widgets"]
  node_depth_cover["3D cover effects"]
end

node_listener(("Listener"))
node_kugou(("Kugou services"))
node_media_store[("Android media store")]

node_listener -->|"uses"| node_flutter
node_flutter -->|"opens"| node_online
node_flutter -->|"browses"| node_local
node_flutter -->|"accesses"| node_user_features
node_flutter -->|"configures"| node_settings
node_online -->|"requests API"| node_kugou_bridge
node_kugou_bridge -->|"starts server"| node_rust_server
node_rust_server -->|"dispatches routes"| node_api_modules
node_api_modules -->|"builds requests"| node_request_layer
node_request_layer -->|"forwards requests"| node_kugou
node_rust_server -->|"reads and writes"| node_api_cache
node_kugou -->|"returns responses"| node_request_layer
node_local -->|"reads tracks"| node_media_store
node_online -->|"selects music"| node_playback_core
node_local -->|"selects tracks"| node_playback_core
node_playback_core -->|"publishes session"| node_session
node_playback_core -->|"processes audio"| node_audio_effects
node_audio_effects -.->|"outputs PCM"| node_usb_native
node_playback_core -->|"provides playback"| node_lyrics
node_playback_core -->|"dispatches commands"| node_floating_lyrics
node_floating_lyrics -->|"sends actions"| node_flutter
node_playback_core -.->|"supports recognition"| node_recognition
node_flutter -.->|"updates"| node_widgets
node_flutter -.->|"enables variant"| node_depth_cover

click node_flutter "https://github.com/zzyoxml/md3music/tree/rust-local-force/lib"
click node_online "https://github.com/zzyoxml/md3music/tree/rust-local-force/lib/modules"
click node_local "https://github.com/zzyoxml/md3music/tree/rust-local-force/lib/modules/library"
click node_user_features "https://github.com/zzyoxml/md3music/tree/rust-local-force/lib/modules/user"
click node_settings "https://github.com/zzyoxml/md3music/tree/rust-local-force/lib/modules/settings"
click node_kugou_bridge "https://github.com/zzyoxml/md3music/blob/rust-local-force/android/app/src/main/kotlin/com/md3music/md3music/KugouApiService.kt"
click node_rust_server "https://github.com/zzyoxml/md3music/blob/rust-local-force/kugou_api_server/rust/src/server.rs"
click node_api_modules "https://github.com/zzyoxml/md3music/tree/rust-local-force/kugou_api_server/rust/src/modules"
click node_request_layer "https://github.com/zzyoxml/md3music/blob/rust-local-force/kugou_api_server/rust/src/request.rs"
click node_api_cache "https://github.com/zzyoxml/md3music/blob/rust-local-force/kugou_api_server/rust/src/cache.rs"
click node_playback_core "https://github.com/zzyoxml/md3music/blob/rust-local-force/android/app/src/main/kotlin/com/md3music/md3music/AudioPlaybackService.kt"
click node_session "https://github.com/zzyoxml/md3music/blob/rust-local-force/android/app/src/main/kotlin/com/md3music/md3music/MD3MusicMediaSessionService.kt"
click node_audio_effects "https://github.com/zzyoxml/md3music/tree/rust-local-force/android/app/src/main/kotlin/com/md3music/md3music"
click node_usb_native "https://github.com/zzyoxml/md3music/blob/rust-local-force/android/app/src/main/cpp/usb-audio-output.cpp"
click node_lyrics "https://github.com/zzyoxml/md3music/tree/rust-local-force/lib/modules/player"
click node_floating_lyrics "https://github.com/zzyoxml/md3music/blob/rust-local-force/android/app/src/main/kotlin/com/md3music/md3music/FloatingLyricService.kt"
click node_recognition "https://github.com/zzyoxml/md3music/blob/rust-local-force/android/app/src/main/kotlin/com/md3music/md3music/FloatingRecognitionService.kt"
click node_widgets "https://github.com/zzyoxml/md3music/blob/rust-local-force/android/app/src/main/kotlin/com/md3music/md3music/MusicWidgetProvider.kt"
click node_depth_cover "https://github.com/zzyoxml/md3music/blob/rust-local-force/android/app/src/depth3d/kotlin/com/md3music/md3music/DepthCoverPlugin.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_flutter,node_online,node_local,node_user_features,node_settings toneBlue
class node_kugou_bridge,node_rust_server,node_api_modules,node_request_layer,node_api_cache,node_media_store toneAmber
class node_playback_core,node_session,node_audio_effects,node_usb_native toneMint
class node_lyrics,node_floating_lyrics,node_recognition,node_widgets,node_depth_cover toneRose
class node_listener,node_kugou toneIndigo
```

## Components

### Flutter app

- [Flutter application](https://github.com/zzyoxml/md3music/tree/rust-local-force/lib): `lib`
- [Online music](https://github.com/zzyoxml/md3music/tree/rust-local-force/lib/modules): `lib/modules`
- [Local library](https://github.com/zzyoxml/md3music/tree/rust-local-force/lib/modules/library): `lib/modules/library`
- [User features](https://github.com/zzyoxml/md3music/tree/rust-local-force/lib/modules/user): `lib/modules/user`
- [Settings and themes](https://github.com/zzyoxml/md3music/tree/rust-local-force/lib/modules/settings): `lib/modules/settings`

### Embedded API

- [API server bridge](https://github.com/zzyoxml/md3music/blob/rust-local-force/android/app/src/main/kotlin/com/md3music/md3music/KugouApiService.kt): `android/app/src/main/kotlin/com/md3music/md3music/KugouApiService.kt`
- [HTTP server](https://github.com/zzyoxml/md3music/blob/rust-local-force/kugou_api_server/rust/src/server.rs): `kugou_api_server/rust/src/server.rs`
- [Kugou endpoints](https://github.com/zzyoxml/md3music/tree/rust-local-force/kugou_api_server/rust/src/modules): `kugou_api_server/rust/src/modules`
- [Request handling](https://github.com/zzyoxml/md3music/blob/rust-local-force/kugou_api_server/rust/src/request.rs): `kugou_api_server/rust/src/request.rs`
- [Response cache](https://github.com/zzyoxml/md3music/blob/rust-local-force/kugou_api_server/rust/src/cache.rs): `kugou_api_server/rust/src/cache.rs`

### Playback and audio

- [Audio playback service](https://github.com/zzyoxml/md3music/blob/rust-local-force/android/app/src/main/kotlin/com/md3music/md3music/AudioPlaybackService.kt): `android/app/src/main/kotlin/com/md3music/md3music/AudioPlaybackService.kt`
- [Media session](https://github.com/zzyoxml/md3music/blob/rust-local-force/android/app/src/main/kotlin/com/md3music/md3music/MD3MusicMediaSessionService.kt): `android/app/src/main/kotlin/com/md3music/md3music/MD3MusicMediaSessionService.kt`
- [Audio processing](https://github.com/zzyoxml/md3music/tree/rust-local-force/android/app/src/main/kotlin/com/md3music/md3music): `android/app/src/main/kotlin/com/md3music/md3music`
- [USB audio output](https://github.com/zzyoxml/md3music/blob/rust-local-force/android/app/src/main/cpp/usb-audio-output.cpp): `android/app/src/main/cpp/usb-audio-output.cpp`

### Lyrics and surfaces

- [Lyric experiences](https://github.com/zzyoxml/md3music/tree/rust-local-force/lib/modules/player): `lib/modules/player`
- [Floating lyrics](https://github.com/zzyoxml/md3music/blob/rust-local-force/android/app/src/main/kotlin/com/md3music/md3music/FloatingLyricService.kt): `android/app/src/main/kotlin/com/md3music/md3music/FloatingLyricService.kt`
- [Floating recognition](https://github.com/zzyoxml/md3music/blob/rust-local-force/android/app/src/main/kotlin/com/md3music/md3music/FloatingRecognitionService.kt): `android/app/src/main/kotlin/com/md3music/md3music/FloatingRecognitionService.kt`
- [Home widgets](https://github.com/zzyoxml/md3music/blob/rust-local-force/android/app/src/main/kotlin/com/md3music/md3music/MusicWidgetProvider.kt): `android/app/src/main/kotlin/com/md3music/md3music/MusicWidgetProvider.kt`
- [3D cover effects](https://github.com/zzyoxml/md3music/blob/rust-local-force/android/app/src/depth3d/kotlin/com/md3music/md3music/DepthCoverPlugin.kt): `android/app/src/depth3d/kotlin/com/md3music/md3music/DepthCoverPlugin.kt`

### Other components

- **Listener**
- **Kugou services**
- **Android media store**

## Connections

- Listener → Flutter application: uses
- Flutter application → Online music: opens
- Flutter application → Local library: browses
- Flutter application → User features: accesses
- Flutter application → Settings and themes: configures
- Online music → API server bridge: requests API
- API server bridge → HTTP server: starts server
- HTTP server → Kugou endpoints: dispatches routes
- Kugou endpoints → Request handling: builds requests
- Request handling → Kugou services: forwards requests
- HTTP server → Response cache: reads and writes
- Kugou services → Request handling: returns responses
- Local library → Android media store: reads tracks
- Online music → Audio playback service: selects music
- Local library → Audio playback service: selects tracks
- Audio playback service → Media session: publishes session
- Audio playback service → Audio processing: processes audio
- Audio processing → USB audio output: outputs PCM
- Audio playback service → Lyric experiences: provides playback
- Audio playback service → Floating lyrics: dispatches commands
- Floating lyrics → Flutter application: sends actions
- Audio playback service → Floating recognition: supports recognition
- Flutter application → Home widgets: updates
- Flutter application → 3D cover effects: enables variant