# xokeza/yamusicmod architecture

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

- Interactive diagram: https://gitdiagram.com/xokeza/yamusicmod
- Repository: https://github.com/xokeza/yamusicmod

## Overview

LLMusic-mod extends the installed Yandex Music desktop client. The main workflow starts with the Electron process initializing settings and the app window, then connects renderer events to added playback and account features; users experience those features through the client and the separate mini-player. The graph also preserves README-documented capabilities whose implementation files were not sampled. Those links are documented behavior, not claims that unsampled call paths were inspected.

Main entry points: [`src/main/index.js`](https://github.com/xokeza/yamusicmod/blob/main/src/main/index.js) (Electron Startup), [`src/main/events.js`](https://github.com/xokeza/yamusicmod/blob/main/src/main/events.js) (Renderer IPC), [`src/main/lib/store.js`](https://github.com/xokeza/yamusicmod/blob/main/src/main/lib/store.js) (Settings Store), [`src/main/lib/yandexStation/YandexStationService.js`](https://github.com/xokeza/yamusicmod/blob/main/src/main/lib/yandexStation/YandexStationService.js) (Yandex Station Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Desktop Runtime"]
  node_main["Electron Startup<br/>[index.js]"]
  node_events["Renderer IPC<br/>[events.js]"]
  node_settings[("Settings Store<br/>[store.js]")]
  node_background["Background Tasks"]
  node_config["App Configuration<br/>[config.js]"]
end

subgraph group_playback["Playback Extensions"]
  node_station["Yandex Station"]
  node_stationauth["Station Authentication"]
  node_remote["Remote Playback<br/>[events.js]"]
  node_exclusive["WASAPI Exclusive<br/>[stream-session.js]"]
  node_nativeaudio["Native Audio Output"]
  node_stationservice["Yandex Station Service"]
end

subgraph group_account["Account Integrations"]
  node_scrobble["Last.fm Scrobbling"]
  node_discord["Discord Status<br/>[events.js]"]
  node_lyrics["LRCLib Lyrics<br/>[corsHandler.js]"]
end

subgraph group_interface["Player Interface"]
  node_miniplayer["Mini-player Window<br/>[miniplayer.js]"]
  node_miniapp["Mini-player UI<br/>[App.jsx]"]
  node_playerstate["Player State Bridge<br/>[PlayerContext.jsx]"]
  node_taskbar["Taskbar Controls"]
  node_hotkeys["Global Shortcuts<br/>[events.js]"]
  node_thumbnail["Taskbar Thumbnail<br/>[index.js]"]
end

subgraph group_support["Client Support"]
  node_logger["Logging<br/>[Logger.js]"]
  node_cors["Request CORS<br/>[corsHandler.js]"]
  node_pulse["PulseSync Add-ons"]
  node_downloader["Track Downloads<br/>[trackDownloader.js]"]
  node_downloadstage["Download Pipeline<br/>[pipelineStage.js]"]
  node_cache["Custom Cache Path<br/>[index.js]"]
  node_stats["Usage Metrics<br/>[metrics.js]"]
end

node_user(("Listener"))
node_lastfm(("Last.fm"))
node_discordsvc(("Discord"))
node_yandexstation(("Yandex Station Device"))
node_lrclibsvc(("LRCLib"))

node_user -->|"starts client"| node_main
node_main -->|"initializes"| node_settings
node_main -->|"loads"| node_miniplayer
node_main -->|"starts tasks"| node_background
node_main -->|"loads handlers"| node_events
node_main -->|"reads config"| node_config
node_main -->|"initializes metrics"| node_stats
node_background -->|"requests refresh"| node_events
node_events -->|"reads and writes"| node_settings
node_settings -->|"sends updates"| node_events
node_miniplayer -.->|"opens window"| node_miniapp
node_miniapp -->|"uses context"| node_playerstate
node_playerstate -.->|"requests state"| node_miniplayer
node_main -.->|"loads add-ons"| node_pulse
node_pulse -->|"reads settings"| node_settings
node_pulse -->|"uses CORS handler"| node_cors
node_main -.->|"starts service"| node_stationservice
node_stationservice -.->|"authenticates"| node_stationauth
node_stationservice -.->|"streams playback"| node_yandexstation
node_user -->|"controls playback"| node_remote
node_remote -.->|"dispatches controls"| node_events
node_main -->|"loads output"| node_nativeaudio
node_nativeaudio -.->|"uses backend"| node_exclusive
node_main -.->|"loads integration"| node_scrobble
node_scrobble -.->|"submits scrobbles"| node_lastfm
node_events -.->|"updates status"| node_discord
node_discord -.->|"publishes status"| node_discordsvc
node_events -->|"manages downloads"| node_downloader
node_downloader -.->|"uses pipeline"| node_downloadstage
node_main -->|"loads controls"| node_taskbar
node_main -->|"sets storage path"| node_cache
node_events -.->|"registers shortcuts"| node_hotkeys
node_cors -->|"allows requests"| node_lrclibsvc
node_user -.->|"views lyrics"| node_lyrics
node_main -.->|"loads thumbnail"| node_thumbnail
node_events -.->|"updates controls"| node_taskbar

click node_main "https://github.com/xokeza/yamusicmod/blob/main/src/main/index.js"
click node_events "https://github.com/xokeza/yamusicmod/blob/main/src/main/events.js"
click node_settings "https://github.com/xokeza/yamusicmod/blob/main/src/main/lib/store.js"
click node_background "https://github.com/xokeza/yamusicmod/blob/main/src/main/lib/handlers/handleBackgroundTasks.js"
click node_config "https://github.com/xokeza/yamusicmod/blob/main/src/main/config.js"
click node_logger "https://github.com/xokeza/yamusicmod/blob/main/src/main/packages/logger/Logger.js"
click node_miniplayer "https://github.com/xokeza/yamusicmod/blob/main/src/main/lib/miniplayer/miniplayer.js"
click node_miniapp "https://github.com/xokeza/yamusicmod/blob/main/miniplayer/src/App.jsx"
click node_playerstate "https://github.com/xokeza/yamusicmod/blob/main/miniplayer/src/contexts/PlayerContext.jsx"
click node_cors "https://github.com/xokeza/yamusicmod/blob/main/src/main/lib/handlers/handleHeadersReceived/corsHandler.js"
click node_pulse "https://github.com/xokeza/yamusicmod/blob/main/src/main/lib/pulsesync/PulseSyncManager.js"
click node_station "https://github.com/xokeza/yamusicmod/blob/main/src/main/lib/yandexStation/YandexStationService.js"
click node_stationauth "https://github.com/xokeza/yamusicmod/blob/main/src/main/lib/yandexStation/YandexAuthClient.js"
click node_remote "https://github.com/xokeza/yamusicmod/blob/main/src/main/events.js"
click node_exclusive "https://github.com/xokeza/yamusicmod/blob/main/native/wasapiExclusive/js/stream-session.js"
click node_nativeaudio "https://github.com/xokeza/yamusicmod/blob/main/src/main/lib/nativeAudioOutput.js"
click node_scrobble "https://github.com/xokeza/yamusicmod/blob/main/src/main/lib/scrobble/ScrobblerManager.js"
click node_discord "https://github.com/xokeza/yamusicmod/blob/main/src/main/events.js"
click node_downloader "https://github.com/xokeza/yamusicmod/blob/main/src/main/lib/trackDownloader/trackDownloader.js"
click node_downloadstage "https://github.com/xokeza/yamusicmod/blob/main/src/main/lib/trackDownloader/pipelineStage.js"
click node_taskbar "https://github.com/xokeza/yamusicmod/blob/main/src/main/lib/taskBarExtension/taskBarExtension.js"
click node_cache "https://github.com/xokeza/yamusicmod/blob/main/src/main/index.js"
click node_hotkeys "https://github.com/xokeza/yamusicmod/blob/main/src/main/events.js"
click node_lyrics "https://github.com/xokeza/yamusicmod/blob/main/src/main/lib/handlers/handleHeadersReceived/corsHandler.js"
click node_thumbnail "https://github.com/xokeza/yamusicmod/blob/main/native/setIconicThumbnail/js/index.js"
click node_stats "https://github.com/xokeza/yamusicmod/blob/main/src/main/lib/metrics.js"
click node_stationservice "https://github.com/xokeza/yamusicmod/blob/main/src/main/lib/yandexStation/YandexStationService.js"

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_main,node_events,node_settings,node_background,node_config toneBlue
class node_station,node_stationauth,node_remote,node_exclusive,node_nativeaudio,node_stationservice toneAmber
class node_scrobble,node_discord,node_lyrics toneMint
class node_miniplayer,node_miniapp,node_playerstate,node_taskbar,node_hotkeys,node_thumbnail toneRose
class node_logger,node_cors,node_pulse,node_downloader,node_downloadstage,node_cache,node_stats,node_user,node_lastfm,node_discordsvc,node_yandexstation,node_lrclibsvc toneIndigo
```

## Components

### Desktop Runtime

- [Electron Startup](https://github.com/xokeza/yamusicmod/blob/main/src/main/index.js): `src/main/index.js`
- [Renderer IPC](https://github.com/xokeza/yamusicmod/blob/main/src/main/events.js): `src/main/events.js`
- [Settings Store](https://github.com/xokeza/yamusicmod/blob/main/src/main/lib/store.js): `src/main/lib/store.js`
- [Background Tasks](https://github.com/xokeza/yamusicmod/blob/main/src/main/lib/handlers/handleBackgroundTasks.js): `src/main/lib/handlers/handleBackgroundTasks.js`
- [App Configuration](https://github.com/xokeza/yamusicmod/blob/main/src/main/config.js): `src/main/config.js`

### Playback Extensions

- [Yandex Station](https://github.com/xokeza/yamusicmod/blob/main/src/main/lib/yandexStation/YandexStationService.js): `src/main/lib/yandexStation/YandexStationService.js`
- [Station Authentication](https://github.com/xokeza/yamusicmod/blob/main/src/main/lib/yandexStation/YandexAuthClient.js): `src/main/lib/yandexStation/YandexAuthClient.js`
- [Remote Playback](https://github.com/xokeza/yamusicmod/blob/main/src/main/events.js): `src/main/events.js`
- [WASAPI Exclusive](https://github.com/xokeza/yamusicmod/blob/main/native/wasapiExclusive/js/stream-session.js): `native/wasapiExclusive/js/stream-session.js`
- [Native Audio Output](https://github.com/xokeza/yamusicmod/blob/main/src/main/lib/nativeAudioOutput.js): `src/main/lib/nativeAudioOutput.js`
- [Yandex Station Service](https://github.com/xokeza/yamusicmod/blob/main/src/main/lib/yandexStation/YandexStationService.js): `src/main/lib/yandexStation/YandexStationService.js`

### Account Integrations

- [Last.fm Scrobbling](https://github.com/xokeza/yamusicmod/blob/main/src/main/lib/scrobble/ScrobblerManager.js): `src/main/lib/scrobble/ScrobblerManager.js`
- [Discord Status](https://github.com/xokeza/yamusicmod/blob/main/src/main/events.js): `src/main/events.js`
- [LRCLib Lyrics](https://github.com/xokeza/yamusicmod/blob/main/src/main/lib/handlers/handleHeadersReceived/corsHandler.js): `src/main/lib/handlers/handleHeadersReceived/corsHandler.js`

### Player Interface

- [Mini-player Window](https://github.com/xokeza/yamusicmod/blob/main/src/main/lib/miniplayer/miniplayer.js): `src/main/lib/miniplayer/miniplayer.js`
- [Mini-player UI](https://github.com/xokeza/yamusicmod/blob/main/miniplayer/src/App.jsx): `miniplayer/src/App.jsx`
- [Player State Bridge](https://github.com/xokeza/yamusicmod/blob/main/miniplayer/src/contexts/PlayerContext.jsx): `miniplayer/src/contexts/PlayerContext.jsx`
- [Taskbar Controls](https://github.com/xokeza/yamusicmod/blob/main/src/main/lib/taskBarExtension/taskBarExtension.js): `src/main/lib/taskBarExtension/taskBarExtension.js`
- [Global Shortcuts](https://github.com/xokeza/yamusicmod/blob/main/src/main/events.js): `src/main/events.js`
- [Taskbar Thumbnail](https://github.com/xokeza/yamusicmod/blob/main/native/setIconicThumbnail/js/index.js): `native/setIconicThumbnail/js/index.js`

### Client Support

- [Logging](https://github.com/xokeza/yamusicmod/blob/main/src/main/packages/logger/Logger.js): `src/main/packages/logger/Logger.js`
- [Request CORS](https://github.com/xokeza/yamusicmod/blob/main/src/main/lib/handlers/handleHeadersReceived/corsHandler.js): `src/main/lib/handlers/handleHeadersReceived/corsHandler.js`
- [PulseSync Add-ons](https://github.com/xokeza/yamusicmod/blob/main/src/main/lib/pulsesync/PulseSyncManager.js): `src/main/lib/pulsesync/PulseSyncManager.js`
- [Track Downloads](https://github.com/xokeza/yamusicmod/blob/main/src/main/lib/trackDownloader/trackDownloader.js): `src/main/lib/trackDownloader/trackDownloader.js`
- [Download Pipeline](https://github.com/xokeza/yamusicmod/blob/main/src/main/lib/trackDownloader/pipelineStage.js): `src/main/lib/trackDownloader/pipelineStage.js`
- [Custom Cache Path](https://github.com/xokeza/yamusicmod/blob/main/src/main/index.js): `src/main/index.js`
- [Usage Metrics](https://github.com/xokeza/yamusicmod/blob/main/src/main/lib/metrics.js): `src/main/lib/metrics.js`

### Other components

- **Listener**
- **Last.fm**
- **Discord**
- **Yandex Station Device**
- **LRCLib**

## Connections

- Listener → Electron Startup: starts client (evidence: `README.md`)
- Electron Startup → Settings Store: initializes (evidence: `src/main/index.js`)
- Electron Startup → Mini-player Window: loads (evidence: `src/main/index.js`)
- Electron Startup → Background Tasks: starts tasks (evidence: `src/main/index.js`)
- Electron Startup → Renderer IPC: loads handlers (evidence: `src/main/index.js`)
- Electron Startup → App Configuration: reads config (evidence: `src/main/index.js`)
- Electron Startup → Usage Metrics: initializes metrics (evidence: `src/main/index.js`)
- Background Tasks → Renderer IPC: requests refresh (evidence: `src/main/lib/handlers/handleBackgroundTasks.js`)
- Renderer IPC → Settings Store: reads and writes (evidence: `src/main/events.js`)
- Settings Store → Renderer IPC: sends updates (evidence: `src/main/lib/store.js`)
- Mini-player Window → Mini-player UI: opens window
- Mini-player UI → Player State Bridge: uses context (evidence: `miniplayer/src/App.jsx`)
- Player State Bridge → Mini-player Window: requests state
- Electron Startup → PulseSync Add-ons: loads add-ons
- PulseSync Add-ons → Settings Store: reads settings (evidence: `src/main/lib/pulsesync/PulseSyncManager.js`)
- PulseSync Add-ons → Request CORS: uses CORS handler (evidence: `src/main/lib/pulsesync/PulseSyncManager.js`)
- Electron Startup → Yandex Station Service: starts service
- Yandex Station Service → Station Authentication: authenticates
- Yandex Station Service → Yandex Station Device: streams playback (evidence: `README.md`)
- Listener → Remote Playback: controls playback (evidence: `README.md`)
- Remote Playback → Renderer IPC: dispatches controls (evidence: `src/main/events.js`)
- Electron Startup → Native Audio Output: loads output (evidence: `src/main/index.js`)
- Native Audio Output → WASAPI Exclusive: uses backend
- Electron Startup → Last.fm Scrobbling: loads integration
- Last.fm Scrobbling → Last.fm: submits scrobbles (evidence: `README.md`)
- Renderer IPC → Discord Status: updates status (evidence: `README.md`)
- Discord Status → Discord: publishes status (evidence: `README.md`)
- Renderer IPC → Track Downloads: manages downloads (evidence: `src/main/events.js`)
- Track Downloads → Download Pipeline: uses pipeline
- Electron Startup → Taskbar Controls: loads controls (evidence: `src/main/index.js`)
- Electron Startup → Custom Cache Path: sets storage path (evidence: `src/main/index.js`)
- Renderer IPC → Global Shortcuts: registers shortcuts (evidence: `README.md`)
- Request CORS → LRCLib: allows requests (evidence: `src/main/lib/handlers/handleHeadersReceived/corsHandler.js`)
- Listener → LRCLib Lyrics: views lyrics (evidence: `README.md`)
- Electron Startup → Taskbar Thumbnail: loads thumbnail
- Renderer IPC → Taskbar Controls: updates controls (evidence: `src/main/events.js`)
