# xwsjjctz/lyricsadapter architecture

> Architecture diagram of the GitHub repository xwsjjctz/lyricsadapter, 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/xwsjjctz/lyricsadapter
- Repository: https://github.com/xwsjjctz/lyricsadapter

## Overview

LyricsAdapter is an Electron desktop music player centered on importing and managing a local library, playing tracks with synchronized lyrics, and extending playback to online providers and WebDAV. The renderer composes UI, controllers, and view models; Electron exposes privileged file, persistence, streaming, and system-integration capabilities through IPC and custom protocols. The README documents major features whose detailed implementations were not sampled, so those branches use supported directory paths and only documented relationships.

Main entry points: [`src/App.tsx`](https://github.com/xwsjjctz/lyricsadapter/blob/master/src/App.tsx) (Application composition), [`electron/ipc`](https://github.com/xwsjjctz/lyricsadapter/tree/master/electron/ipc) (IPC handlers), [`electron/main.ts`](https://github.com/xwsjjctz/lyricsadapter/blob/master/electron/main.ts) (Electron main), [`src/controllers/useLibraryController.ts`](https://github.com/xwsjjctz/lyricsadapter/blob/master/src/controllers/useLibraryController.ts) (Library controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_renderer["Renderer experience"]
  node_app["Application composition<br/>[App.tsx]"]
  node_ui["Views and controls"]
  node_lyrics["Lyrics presentation<br/>[FocusLyrics.tsx]"]
end

subgraph group_music["Music workflows"]
  node_player["Playback controller"]
  node_library["Library controller"]
  node_import["Track import<br/>[useImport.ts]"]
  node_metadata["Metadata and lyrics<br/>[metadataService.ts]"]
  node_online["Online music"]
  node_providers["QQ and NetEase<br/>[qqMusicApi.ts]"]
  node_webdav["WebDAV library<br/>[webdavClient.ts]"]
end

subgraph group_desktop["Desktop runtime"]
  node_main["Electron main<br/>[main.ts]"]
  node_preload["IPC bridge<br/>[preload.ts]"]
  node_handlers["IPC handlers"]
  node_protocols["Media protocols"]
  node_metadataio["Audio metadata service"]
end

subgraph group_state["Persistence and settings"]
  node_librarydata["Library persistence<br/>[libraryStorage.ts]"]
  node_indexeddb[("Metadata cache")]
  node_settings["Settings storage<br/>[appStorage.ts]"]
  node_stateapi[("User state repository")]
end

subgraph group_integrations["Platform integrations"]
  node_systemlyrics["System lyrics coordinator"]
  node_native["Native system surfaces"]
  node_host["Windows taskbar host<br/>[App.xaml.cs]"]
  node_media["System media controls<br/>[useMediaSession.ts]"]
  node_updater["Application updater<br/>[updater.ts]"]
end

node_listener(("Listener"))
node_platform(("Operating system"))
node_services(("Online services"))
node_webdavserver(("WebDAV server"))

node_listener -->|"operates"| node_ui
node_ui -->|"user intent"| node_app
node_app -->|"composes"| node_player
node_app -->|"composes"| node_library
node_app -->|"composes"| node_import
node_app -->|"composes"| node_online
node_player -->|"gets lyrics"| node_online
node_online -->|"queries"| node_providers
node_providers -->|"requests"| node_services
node_player -->|"provides track state"| node_lyrics
node_listener -->|"imports and manages"| node_library
node_import -->|"extracts tags"| node_metadata
node_library -->|"loads and saves"| node_librarydata
node_library -->|"uses cache"| node_indexeddb
node_app -->|"configures"| node_settings
node_settings -->|"requests settings"| node_preload
node_preload -->|"dispatches IPC"| node_handlers
node_main -->|"registers"| node_handlers
node_handlers -->|"reads and writes"| node_stateapi
node_handlers -->|"invokes"| node_metadataio
node_handlers -->|"invokes"| node_webdav
node_webdav -->|"browses and streams"| node_webdavserver
node_main -->|"registers"| node_protocols
node_protocols -->|"reads audio and covers"| node_platform
node_librarydata -->|"requests library data"| node_preload
node_main -->|"initializes"| node_systemlyrics
node_systemlyrics -->|"updates surface"| node_native
node_native -.->|"launches host"| node_host
node_systemlyrics -->|"sends playback actions"| node_preload
node_app -->|"publishes playback state"| node_media
node_media -->|"publishes controls"| node_platform
node_main -->|"initializes"| node_updater
node_updater -.->|"checks releases"| node_services

click node_app "https://github.com/xwsjjctz/lyricsadapter/blob/master/src/App.tsx"
click node_ui "https://github.com/xwsjjctz/lyricsadapter/tree/master/src/components"
click node_player "https://github.com/xwsjjctz/lyricsadapter/blob/master/src/controllers/usePlayerController.ts"
click node_library "https://github.com/xwsjjctz/lyricsadapter/blob/master/src/controllers/useLibraryController.ts"
click node_import "https://github.com/xwsjjctz/lyricsadapter/blob/master/src/hooks/useImport.ts"
click node_metadata "https://github.com/xwsjjctz/lyricsadapter/blob/master/src/services/metadataService.ts"
click node_lyrics "https://github.com/xwsjjctz/lyricsadapter/blob/master/src/components/focus-mode/FocusLyrics.tsx"
click node_online "https://github.com/xwsjjctz/lyricsadapter/blob/master/src/services/onlineMusicProvider.ts"
click node_providers "https://github.com/xwsjjctz/lyricsadapter/blob/master/src/services/qqMusicApi.ts"
click node_webdav "https://github.com/xwsjjctz/lyricsadapter/blob/master/src/services/webdavClient.ts"
click node_librarydata "https://github.com/xwsjjctz/lyricsadapter/blob/master/src/services/libraryStorage.ts"
click node_indexeddb "https://github.com/xwsjjctz/lyricsadapter/blob/master/src/services/indexedDBStorage.ts"
click node_settings "https://github.com/xwsjjctz/lyricsadapter/blob/master/src/services/appStorage.ts"
click node_main "https://github.com/xwsjjctz/lyricsadapter/blob/master/electron/main.ts"
click node_preload "https://github.com/xwsjjctz/lyricsadapter/blob/master/electron/preload.ts"
click node_handlers "https://github.com/xwsjjctz/lyricsadapter/tree/master/electron/ipc"
click node_protocols "https://github.com/xwsjjctz/lyricsadapter/tree/master/electron/protocols"
click node_stateapi "https://github.com/xwsjjctz/lyricsadapter/blob/master/electron/services/userStateRepository.ts"
click node_metadataio "https://github.com/xwsjjctz/lyricsadapter/blob/master/electron/services/audioMetadataService.ts"
click node_systemlyrics "https://github.com/xwsjjctz/lyricsadapter/blob/master/electron/services/systemLyricsCoordinator.ts"
click node_native "https://github.com/xwsjjctz/lyricsadapter/tree/master/electron/native"
click node_host "https://github.com/xwsjjctz/lyricsadapter/blob/master/native/windows-taskbar-host/App.xaml.cs"
click node_media "https://github.com/xwsjjctz/lyricsadapter/blob/master/src/hooks/useMediaSession.ts"
click node_updater "https://github.com/xwsjjctz/lyricsadapter/blob/master/electron/updater.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,node_ui,node_lyrics toneBlue
class node_player,node_library,node_import,node_metadata,node_online,node_providers,node_webdav toneAmber
class node_main,node_preload,node_handlers,node_protocols,node_metadataio,node_webdavserver toneMint
class node_librarydata,node_indexeddb,node_settings,node_stateapi toneRose
class node_systemlyrics,node_native,node_host,node_media,node_updater,node_listener,node_platform,node_services toneIndigo
```

## Components

### Renderer experience

- [Application composition](https://github.com/xwsjjctz/lyricsadapter/blob/master/src/App.tsx): `src/App.tsx`
- [Views and controls](https://github.com/xwsjjctz/lyricsadapter/tree/master/src/components): `src/components`
- [Lyrics presentation](https://github.com/xwsjjctz/lyricsadapter/blob/master/src/components/focus-mode/FocusLyrics.tsx): `src/components/focus-mode/FocusLyrics.tsx`

### Music workflows

- [Playback controller](https://github.com/xwsjjctz/lyricsadapter/blob/master/src/controllers/usePlayerController.ts): `src/controllers/usePlayerController.ts`
- [Library controller](https://github.com/xwsjjctz/lyricsadapter/blob/master/src/controllers/useLibraryController.ts): `src/controllers/useLibraryController.ts`
- [Track import](https://github.com/xwsjjctz/lyricsadapter/blob/master/src/hooks/useImport.ts): `src/hooks/useImport.ts`
- [Metadata and lyrics](https://github.com/xwsjjctz/lyricsadapter/blob/master/src/services/metadataService.ts): `src/services/metadataService.ts`
- [Online music](https://github.com/xwsjjctz/lyricsadapter/blob/master/src/services/onlineMusicProvider.ts): `src/services/onlineMusicProvider.ts`
- [QQ and NetEase](https://github.com/xwsjjctz/lyricsadapter/blob/master/src/services/qqMusicApi.ts): `src/services/qqMusicApi.ts`
- [WebDAV library](https://github.com/xwsjjctz/lyricsadapter/blob/master/src/services/webdavClient.ts): `src/services/webdavClient.ts`

### Desktop runtime

- [Electron main](https://github.com/xwsjjctz/lyricsadapter/blob/master/electron/main.ts): `electron/main.ts`
- [IPC bridge](https://github.com/xwsjjctz/lyricsadapter/blob/master/electron/preload.ts): `electron/preload.ts`
- [IPC handlers](https://github.com/xwsjjctz/lyricsadapter/tree/master/electron/ipc): `electron/ipc`
- [Media protocols](https://github.com/xwsjjctz/lyricsadapter/tree/master/electron/protocols): `electron/protocols`
- [Audio metadata service](https://github.com/xwsjjctz/lyricsadapter/blob/master/electron/services/audioMetadataService.ts): `electron/services/audioMetadataService.ts`

### Persistence and settings

- [Library persistence](https://github.com/xwsjjctz/lyricsadapter/blob/master/src/services/libraryStorage.ts): `src/services/libraryStorage.ts`
- [Metadata cache](https://github.com/xwsjjctz/lyricsadapter/blob/master/src/services/indexedDBStorage.ts): `src/services/indexedDBStorage.ts`
- [Settings storage](https://github.com/xwsjjctz/lyricsadapter/blob/master/src/services/appStorage.ts): `src/services/appStorage.ts`
- [User state repository](https://github.com/xwsjjctz/lyricsadapter/blob/master/electron/services/userStateRepository.ts): `electron/services/userStateRepository.ts`

### Platform integrations

- [System lyrics coordinator](https://github.com/xwsjjctz/lyricsadapter/blob/master/electron/services/systemLyricsCoordinator.ts): `electron/services/systemLyricsCoordinator.ts`
- [Native system surfaces](https://github.com/xwsjjctz/lyricsadapter/tree/master/electron/native): `electron/native`
- [Windows taskbar host](https://github.com/xwsjjctz/lyricsadapter/blob/master/native/windows-taskbar-host/App.xaml.cs): `native/windows-taskbar-host/App.xaml.cs`
- [System media controls](https://github.com/xwsjjctz/lyricsadapter/blob/master/src/hooks/useMediaSession.ts): `src/hooks/useMediaSession.ts`
- [Application updater](https://github.com/xwsjjctz/lyricsadapter/blob/master/electron/updater.ts): `electron/updater.ts`

### Other components

- **Listener**
- **Operating system**
- **Online services**
- **WebDAV server**

## Connections

- Listener → Views and controls: operates
- Views and controls → Application composition: user intent
- Application composition → Playback controller: composes
- Application composition → Library controller: composes
- Application composition → Track import: composes
- Application composition → Online music: composes
- Playback controller → Online music: gets lyrics
- Online music → QQ and NetEase: queries
- QQ and NetEase → Online services: requests
- Playback controller → Lyrics presentation: provides track state
- Listener → Library controller: imports and manages
- Track import → Metadata and lyrics: extracts tags
- Library controller → Library persistence: loads and saves
- Library controller → Metadata cache: uses cache
- Application composition → Settings storage: configures
- Settings storage → IPC bridge: requests settings
- IPC bridge → IPC handlers: dispatches IPC
- Electron main → IPC handlers: registers
- IPC handlers → User state repository: reads and writes
- IPC handlers → Audio metadata service: invokes
- IPC handlers → WebDAV library: invokes
- WebDAV library → WebDAV server: browses and streams
- Electron main → Media protocols: registers
- Media protocols → Operating system: reads audio and covers
- Library persistence → IPC bridge: requests library data
- Electron main → System lyrics coordinator: initializes
- System lyrics coordinator → Native system surfaces: updates surface
- Native system surfaces → Windows taskbar host: launches host
- System lyrics coordinator → IPC bridge: sends playback actions
- Application composition → System media controls: publishes playback state
- System media controls → Operating system: publishes controls
- Electron main → Application updater: initializes
- Application updater → Online services: checks releases