# maotoumao/musicfree architecture

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

- Interactive diagram: https://gitdiagram.com/maotoumao/musicfree
- Repository: https://github.com/maotoumao/musicfree

## Overview

MusicFree is a mobile music player whose audio sources and catalog operations are supplied by user-installed plugins. Users can search for music, explore plugin-provided albums, artists, charts and playlists, then play tracks, manage collections, view lyrics, and download or access local music. The map groups those user-facing capabilities with playback, plugin, and local-state layers. README documents plugin capabilities; sampled source confirms selected wiring, so unverified connections are omitted.

Main entry points: [`src/core/pluginManager/index.ts`](https://github.com/maotoumao/musicfree/blob/master/src/core/pluginManager/index.ts) (Plugin manager), [`src/entry/bootstrap/bootstrap.ts`](https://github.com/maotoumao/musicfree/blob/master/src/entry/bootstrap/bootstrap.ts) (Bootstrap), [`src/core/lyricManager.ts`](https://github.com/maotoumao/musicfree/blob/master/src/core/lyricManager.ts) (Lyrics manager), [`src/core/trackPlayer/index.ts`](https://github.com/maotoumao/musicfree/blob/master/src/core/trackPlayer/index.ts) (Track player)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and navigation"]
  node_app_entry["App entry<br/>[index.tsx]"]
  node_bootstrap["Bootstrap<br/>[bootstrap.ts]"]
  node_routes["Screen routes<br/>[routes.tsx]"]
end

subgraph group_discovery["Music discovery"]
  node_search["Music search<br/>[useSearch.ts]"]
  node_artist["Artist works<br/>[useQuery.ts]"]
  node_album["Album tracks"]
  node_charts["Charts and lists"]
  node_recommendations["Recommended sheets"]
  node_plugin_sheets["Plugin sheets"]
end

subgraph group_playback["Playback and lyrics"]
  node_player["Track player<br/>[index.ts]"]
  node_music_detail["Now playing<br/>[index.tsx]"]
  node_lyrics["Lyrics manager<br/>[lyricManager.ts]"]
  node_lyric_search["Lyric search<br/>[useSearchLrc.ts]"]
  node_native_lyric["Native lyric utility<br/>[index.ts]"]
end

subgraph group_plugins["Plugin integrations"]
  node_plugin_manager["Plugin manager<br/>[index.ts]"]
  node_plugin_modules["Plugin modules<br/>[plugin.ts]"]
end

subgraph group_library["Library and settings"]
  node_local_music["Local music<br/>[localMusicSheet.ts]"]
  node_collections["Music sheets<br/>[index.ts]"]
  node_history["Listening history<br/>[musicHistory.ts]"]
  node_downloads["Downloads<br/>[downloader.ts]"]
  node_settings["Settings and themes<br/>[index.tsx]"]
  node_persisted_state[("Persisted state<br/>[persistStatus.ts]")]
  node_file_storage["Device files<br/>[fileUtils.ts]"]
end

node_listener(("Listener"))

node_listener -->|"opens app"| node_app_entry
node_app_entry -->|"starts"| node_bootstrap
node_app_entry -->|"registers screens"| node_routes
node_routes -->|"routes to"| node_search
node_routes -->|"routes to"| node_music_detail
node_search -->|"queries plugins"| node_plugin_manager
node_artist -->|"gets plugin"| node_plugin_manager
node_album -->|"gets tracks"| node_plugin_manager
node_charts -->|"gets chart"| node_plugin_manager
node_recommendations -->|"gets sheets"| node_plugin_manager
node_plugin_sheets -->|"gets tracks"| node_plugin_manager
node_plugin_manager -->|"loads modules"| node_plugin_modules
node_bootstrap -->|"initializes"| node_plugin_manager
node_bootstrap -->|"initializes"| node_player
node_bootstrap -->|"initializes"| node_collections
node_bootstrap -->|"initializes"| node_lyrics
node_music_detail -.->|"controls playback"| node_player
node_player -->|"notifies track change"| node_lyrics
node_lyrics -->|"searches lyrics"| node_plugin_manager
node_lyric_search -->|"searches plugins"| node_plugin_manager
node_lyrics -->|"sets lyric text"| node_native_lyric
node_lyrics -->|"creates lyric directory"| node_file_storage
node_bootstrap -->|"initializes"| node_local_music
node_bootstrap -->|"initializes"| node_history
node_bootstrap -->|"initializes"| node_downloads
node_settings -.->|"configures"| node_persisted_state
node_player -->|"saves playback state"| node_persisted_state
node_plugin_manager -.->|"stores plugin metadata"| node_persisted_state

click node_app_entry "https://github.com/maotoumao/musicfree/blob/master/src/entry/index.tsx"
click node_bootstrap "https://github.com/maotoumao/musicfree/blob/master/src/entry/bootstrap/bootstrap.ts"
click node_routes "https://github.com/maotoumao/musicfree/blob/master/src/core/router/routes.tsx"
click node_search "https://github.com/maotoumao/musicfree/blob/master/src/pages/searchPage/hooks/useSearch.ts"
click node_artist "https://github.com/maotoumao/musicfree/blob/master/src/pages/artistDetail/hooks/useQuery.ts"
click node_album "https://github.com/maotoumao/musicfree/blob/master/src/pages/albumDetail/hooks/useAlbumMusicList.ts"
click node_charts "https://github.com/maotoumao/musicfree/blob/master/src/pages/topListDetail/hooks/useTopListDetail.ts"
click node_recommendations "https://github.com/maotoumao/musicfree/blob/master/src/pages/recommendSheets/hooks/useRecommendSheets.ts"
click node_plugin_sheets "https://github.com/maotoumao/musicfree/blob/master/src/pages/pluginSheetDetail/hooks/usePluginSheetMusicList.ts"
click node_plugin_manager "https://github.com/maotoumao/musicfree/blob/master/src/core/pluginManager/index.ts"
click node_plugin_modules "https://github.com/maotoumao/musicfree/blob/master/src/core/pluginManager/plugin.ts"
click node_player "https://github.com/maotoumao/musicfree/blob/master/src/core/trackPlayer/index.ts"
click node_music_detail "https://github.com/maotoumao/musicfree/blob/master/src/pages/musicDetail/index.tsx"
click node_lyrics "https://github.com/maotoumao/musicfree/blob/master/src/core/lyricManager.ts"
click node_lyric_search "https://github.com/maotoumao/musicfree/blob/master/src/components/panels/types/searchLrc/useSearchLrc.ts"
click node_local_music "https://github.com/maotoumao/musicfree/blob/master/src/core/localMusicSheet.ts"
click node_collections "https://github.com/maotoumao/musicfree/blob/master/src/core/musicSheet/index.ts"
click node_history "https://github.com/maotoumao/musicfree/blob/master/src/core/musicHistory.ts"
click node_downloads "https://github.com/maotoumao/musicfree/blob/master/src/core/downloader.ts"
click node_settings "https://github.com/maotoumao/musicfree/blob/master/src/pages/setting/index.tsx"
click node_persisted_state "https://github.com/maotoumao/musicfree/blob/master/src/utils/persistStatus.ts"
click node_native_lyric "https://github.com/maotoumao/musicfree/blob/master/src/native/lyricUtil/index.ts"
click node_file_storage "https://github.com/maotoumao/musicfree/blob/master/src/utils/fileUtils.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_app_entry,node_bootstrap,node_routes toneBlue
class node_search,node_artist,node_album,node_charts,node_recommendations,node_plugin_sheets toneAmber
class node_player,node_music_detail,node_lyrics,node_lyric_search,node_native_lyric toneMint
class node_plugin_manager,node_plugin_modules toneRose
class node_local_music,node_collections,node_history,node_downloads,node_settings,node_persisted_state,node_file_storage,node_listener toneIndigo
```

## Components

### App and navigation

- [App entry](https://github.com/maotoumao/musicfree/blob/master/src/entry/index.tsx): `src/entry/index.tsx`
- [Bootstrap](https://github.com/maotoumao/musicfree/blob/master/src/entry/bootstrap/bootstrap.ts): `src/entry/bootstrap/bootstrap.ts`
- [Screen routes](https://github.com/maotoumao/musicfree/blob/master/src/core/router/routes.tsx): `src/core/router/routes.tsx`

### Music discovery

- [Music search](https://github.com/maotoumao/musicfree/blob/master/src/pages/searchPage/hooks/useSearch.ts): `src/pages/searchPage/hooks/useSearch.ts`
- [Artist works](https://github.com/maotoumao/musicfree/blob/master/src/pages/artistDetail/hooks/useQuery.ts): `src/pages/artistDetail/hooks/useQuery.ts`
- [Album tracks](https://github.com/maotoumao/musicfree/blob/master/src/pages/albumDetail/hooks/useAlbumMusicList.ts): `src/pages/albumDetail/hooks/useAlbumMusicList.ts`
- [Charts and lists](https://github.com/maotoumao/musicfree/blob/master/src/pages/topListDetail/hooks/useTopListDetail.ts): `src/pages/topListDetail/hooks/useTopListDetail.ts`
- [Recommended sheets](https://github.com/maotoumao/musicfree/blob/master/src/pages/recommendSheets/hooks/useRecommendSheets.ts): `src/pages/recommendSheets/hooks/useRecommendSheets.ts`
- [Plugin sheets](https://github.com/maotoumao/musicfree/blob/master/src/pages/pluginSheetDetail/hooks/usePluginSheetMusicList.ts): `src/pages/pluginSheetDetail/hooks/usePluginSheetMusicList.ts`

### Playback and lyrics

- [Track player](https://github.com/maotoumao/musicfree/blob/master/src/core/trackPlayer/index.ts): `src/core/trackPlayer/index.ts`
- [Now playing](https://github.com/maotoumao/musicfree/blob/master/src/pages/musicDetail/index.tsx): `src/pages/musicDetail/index.tsx`
- [Lyrics manager](https://github.com/maotoumao/musicfree/blob/master/src/core/lyricManager.ts): `src/core/lyricManager.ts`
- [Lyric search](https://github.com/maotoumao/musicfree/blob/master/src/components/panels/types/searchLrc/useSearchLrc.ts): `src/components/panels/types/searchLrc/useSearchLrc.ts`
- [Native lyric utility](https://github.com/maotoumao/musicfree/blob/master/src/native/lyricUtil/index.ts): `src/native/lyricUtil/index.ts`

### Plugin integrations

- [Plugin manager](https://github.com/maotoumao/musicfree/blob/master/src/core/pluginManager/index.ts): `src/core/pluginManager/index.ts`
- [Plugin modules](https://github.com/maotoumao/musicfree/blob/master/src/core/pluginManager/plugin.ts): `src/core/pluginManager/plugin.ts`

### Library and settings

- [Local music](https://github.com/maotoumao/musicfree/blob/master/src/core/localMusicSheet.ts): `src/core/localMusicSheet.ts`
- [Music sheets](https://github.com/maotoumao/musicfree/blob/master/src/core/musicSheet/index.ts): `src/core/musicSheet/index.ts`
- [Listening history](https://github.com/maotoumao/musicfree/blob/master/src/core/musicHistory.ts): `src/core/musicHistory.ts`
- [Downloads](https://github.com/maotoumao/musicfree/blob/master/src/core/downloader.ts): `src/core/downloader.ts`
- [Settings and themes](https://github.com/maotoumao/musicfree/blob/master/src/pages/setting/index.tsx): `src/pages/setting/index.tsx`
- [Persisted state](https://github.com/maotoumao/musicfree/blob/master/src/utils/persistStatus.ts): `src/utils/persistStatus.ts`
- [Device files](https://github.com/maotoumao/musicfree/blob/master/src/utils/fileUtils.ts): `src/utils/fileUtils.ts`

### Other components

- **Listener**

## Connections

- Listener → App entry: opens app (evidence: `src/entry/index.tsx`)
- App entry → Bootstrap: starts (evidence: `src/entry/index.tsx`)
- App entry → Screen routes: registers screens (evidence: `src/entry/index.tsx`)
- Screen routes → Music search: routes to (evidence: `src/core/router/routes.tsx`)
- Screen routes → Now playing: routes to (evidence: `src/core/router/routes.tsx`)
- Music search → Plugin manager: queries plugins (evidence: `src/pages/searchPage/hooks/useSearch.ts`)
- Artist works → Plugin manager: gets plugin (evidence: `src/pages/artistDetail/hooks/useQuery.ts`)
- Album tracks → Plugin manager: gets tracks (evidence: `src/pages/albumDetail/hooks/useAlbumMusicList.ts`)
- Charts and lists → Plugin manager: gets chart (evidence: `src/pages/topListDetail/hooks/useTopListDetail.ts`)
- Recommended sheets → Plugin manager: gets sheets (evidence: `src/pages/recommendSheets/hooks/useRecommendSheets.ts`)
- Plugin sheets → Plugin manager: gets tracks (evidence: `src/pages/pluginSheetDetail/hooks/usePluginSheetMusicList.ts`)
- Plugin manager → Plugin modules: loads modules (evidence: `src/core/pluginManager/index.ts`)
- Bootstrap → Plugin manager: initializes (evidence: `src/entry/bootstrap/bootstrap.ts`)
- Bootstrap → Track player: initializes (evidence: `src/entry/bootstrap/bootstrap.ts`)
- Bootstrap → Music sheets: initializes (evidence: `src/entry/bootstrap/bootstrap.ts`)
- Bootstrap → Lyrics manager: initializes (evidence: `src/entry/bootstrap/bootstrap.ts`)
- Now playing → Track player: controls playback
- Track player → Lyrics manager: notifies track change (evidence: `src/core/lyricManager.ts`)
- Lyrics manager → Plugin manager: searches lyrics (evidence: `src/core/lyricManager.ts`)
- Lyric search → Plugin manager: searches plugins (evidence: `src/components/panels/types/searchLrc/useSearchLrc.ts`)
- Lyrics manager → Native lyric utility: sets lyric text (evidence: `src/core/lyricManager.ts`)
- Lyrics manager → Device files: creates lyric directory (evidence: `src/core/lyricManager.ts`)
- Bootstrap → Local music: initializes (evidence: `src/entry/bootstrap/bootstrap.ts`)
- Bootstrap → Listening history: initializes (evidence: `src/entry/bootstrap/bootstrap.ts`)
- Bootstrap → Downloads: initializes (evidence: `src/entry/bootstrap/bootstrap.ts`)
- Settings and themes → Persisted state: configures
- Track player → Persisted state: saves playback state (evidence: `src/core/trackPlayer/index.ts`)
- Plugin manager → Persisted state: stores plugin metadata
