# pear-devs/pear-desktop architecture

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

## Overview

Pear Desktop is an Electron desktop experience for YouTube Music, extended through plugins that can alter the native window and renderer UI. The principal flow is user interaction in the desktop player, player-control and song-data providers, then optional plugin features or external integrations. Plugin definitions span backend, preload, renderer and menu lifecycles; persisted configuration governs activation. The README documents the plugin capabilities and lifecycle, while sampled source confirms main-process plugin loading and selected provider/integration wiring; unsampled plugin internals are represented only at their supported directory paths.

Main entry points: [`src/loader/main.ts`](https://github.com/pear-devs/pear-desktop/blob/master/src/loader/main.ts) (Plugin lifecycle), [`src/index.ts`](https://github.com/pear-devs/pear-desktop/blob/master/src/index.ts) (Electron shell), [`src/menu.ts`](https://github.com/pear-devs/pear-desktop/blob/master/src/menu.ts) (Native menus), [`src/plugins/api-server/backend/main.ts`](https://github.com/pear-devs/pear-desktop/blob/master/src/plugins/api-server/backend/main.ts) (Control API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop runtime"]
  node_shell["Electron shell<br/>[index.ts]"]
  node_config[("App configuration<br/>[store.ts]")]
  node_menus["Native menus<br/>[menu.ts]"]
end

subgraph group_player["Player providers"]
  node_songfront["Player data bridge<br/>[song-info-front.ts]"]
  node_songinfo["Song metadata<br/>[song-info.ts]"]
  node_controls["Song controls<br/>[song-controls.ts]"]
  node_appcontrols["App controls<br/>[app-controls.ts]"]
end

subgraph group_plugins["Plugin platform"]
  node_pluginloader["Plugin lifecycle<br/>[main.ts]"]
  node_plugindefs["Plugin definitions<br/>[plugins.ts]"]
  node_pluginapi["Plugin contexts<br/>[contexts.ts]"]
end

subgraph group_features["Player extensions"]
  node_api["Control API<br/>[main.ts]"]
  node_api_routes["API routes<br/>[index.ts]"]
  node_lyrics["Synced lyrics"]
  node_music_together["Shared listening"]
  node_downloader["Music downloader"]
  node_audio["Audio enhancements"]
end

subgraph group_integrations["External integrations"]
  node_discord["Rich presence<br/>[discord-service.ts]"]
  node_scrobbler["Scrobbling"]
  node_discord_service["Discord service<br/>[discord-service.ts]"]
  node_scrobble_services["Scrobble services"]
end

node_user(("Desktop user"))
node_ytm["YouTube Music"]

node_user -->|"uses"| node_shell
node_ytm -.->|"provides player"| node_shell
node_shell -->|"loads plugins"| node_pluginloader
node_pluginloader -->|"loads definitions"| node_plugindefs
node_pluginloader -->|"reads settings"| node_config
node_pluginloader -->|"creates contexts"| node_pluginapi
node_user -->|"configures features"| node_menus
node_menus -->|"loads menu plugins"| node_pluginloader
node_songfront -->|"sends player data"| node_songinfo
node_shell -->|"registers controls"| node_appcontrols
node_api -->|"registers routes"| node_api_routes
node_api_routes -.->|"dispatches controls"| node_controls
node_pluginloader -.->|"activates extension"| node_api
node_pluginloader -.->|"activates extension"| node_lyrics
node_pluginloader -.->|"activates extension"| node_music_together
node_pluginloader -.->|"activates extension"| node_downloader
node_pluginloader -.->|"activates extension"| node_audio
node_pluginloader -.->|"activates extension"| node_discord
node_pluginloader -.->|"activates extension"| node_scrobbler
node_discord -->|"updates presence"| node_discord_service
node_discord_service -->|"reads metadata"| node_songinfo
node_scrobbler -->|"uses services"| node_scrobble_services

click node_shell "https://github.com/pear-devs/pear-desktop/blob/master/src/index.ts"
click node_config "https://github.com/pear-devs/pear-desktop/blob/master/src/config/store.ts"
click node_menus "https://github.com/pear-devs/pear-desktop/blob/master/src/menu.ts"
click node_pluginloader "https://github.com/pear-devs/pear-desktop/blob/master/src/loader/main.ts"
click node_plugindefs "https://github.com/pear-devs/pear-desktop/blob/master/src/types/plugins.ts"
click node_pluginapi "https://github.com/pear-devs/pear-desktop/blob/master/src/types/contexts.ts"
click node_songfront "https://github.com/pear-devs/pear-desktop/blob/master/src/providers/song-info-front.ts"
click node_songinfo "https://github.com/pear-devs/pear-desktop/blob/master/src/providers/song-info.ts"
click node_controls "https://github.com/pear-devs/pear-desktop/blob/master/src/providers/song-controls.ts"
click node_appcontrols "https://github.com/pear-devs/pear-desktop/blob/master/src/providers/app-controls.ts"
click node_api "https://github.com/pear-devs/pear-desktop/blob/master/src/plugins/api-server/backend/main.ts"
click node_api_routes "https://github.com/pear-devs/pear-desktop/blob/master/src/plugins/api-server/backend/routes/index.ts"
click node_lyrics "https://github.com/pear-devs/pear-desktop/tree/master/src/plugins/synced-lyrics"
click node_music_together "https://github.com/pear-devs/pear-desktop/tree/master/src/plugins/music-together"
click node_downloader "https://github.com/pear-devs/pear-desktop/tree/master/src/plugins/downloader"
click node_audio "https://github.com/pear-devs/pear-desktop/tree/master/src/plugins/equalizer"
click node_discord "https://github.com/pear-devs/pear-desktop/blob/master/src/plugins/discord/discord-service.ts"
click node_scrobbler "https://github.com/pear-devs/pear-desktop/tree/master/src/plugins/scrobbler"
click node_discord_service "https://github.com/pear-devs/pear-desktop/blob/master/src/plugins/discord/discord-service.ts"
click node_scrobble_services "https://github.com/pear-devs/pear-desktop/tree/master/src/plugins/scrobbler/services"

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_shell,node_config,node_menus,node_user toneBlue
class node_songfront,node_songinfo,node_controls,node_appcontrols toneAmber
class node_pluginloader,node_plugindefs,node_pluginapi toneMint
class node_api,node_api_routes,node_lyrics,node_music_together,node_downloader,node_audio toneRose
class node_discord,node_scrobbler,node_discord_service,node_scrobble_services,node_ytm toneIndigo
```

## Components

### Desktop runtime

- [Electron shell](https://github.com/pear-devs/pear-desktop/blob/master/src/index.ts): `src/index.ts`
- [App configuration](https://github.com/pear-devs/pear-desktop/blob/master/src/config/store.ts): `src/config/store.ts`
- [Native menus](https://github.com/pear-devs/pear-desktop/blob/master/src/menu.ts): `src/menu.ts`

### Player providers

- [Player data bridge](https://github.com/pear-devs/pear-desktop/blob/master/src/providers/song-info-front.ts): `src/providers/song-info-front.ts`
- [Song metadata](https://github.com/pear-devs/pear-desktop/blob/master/src/providers/song-info.ts): `src/providers/song-info.ts`
- [Song controls](https://github.com/pear-devs/pear-desktop/blob/master/src/providers/song-controls.ts): `src/providers/song-controls.ts`
- [App controls](https://github.com/pear-devs/pear-desktop/blob/master/src/providers/app-controls.ts): `src/providers/app-controls.ts`

### Plugin platform

- [Plugin lifecycle](https://github.com/pear-devs/pear-desktop/blob/master/src/loader/main.ts): `src/loader/main.ts`
- [Plugin definitions](https://github.com/pear-devs/pear-desktop/blob/master/src/types/plugins.ts): `src/types/plugins.ts`
- [Plugin contexts](https://github.com/pear-devs/pear-desktop/blob/master/src/types/contexts.ts): `src/types/contexts.ts`

### Player extensions

- [Control API](https://github.com/pear-devs/pear-desktop/blob/master/src/plugins/api-server/backend/main.ts): `src/plugins/api-server/backend/main.ts`
- [API routes](https://github.com/pear-devs/pear-desktop/blob/master/src/plugins/api-server/backend/routes/index.ts): `src/plugins/api-server/backend/routes/index.ts`
- [Synced lyrics](https://github.com/pear-devs/pear-desktop/tree/master/src/plugins/synced-lyrics): `src/plugins/synced-lyrics`
- [Shared listening](https://github.com/pear-devs/pear-desktop/tree/master/src/plugins/music-together): `src/plugins/music-together`
- [Music downloader](https://github.com/pear-devs/pear-desktop/tree/master/src/plugins/downloader): `src/plugins/downloader`
- [Audio enhancements](https://github.com/pear-devs/pear-desktop/tree/master/src/plugins/equalizer): `src/plugins/equalizer`

### External integrations

- [Rich presence](https://github.com/pear-devs/pear-desktop/blob/master/src/plugins/discord/discord-service.ts): `src/plugins/discord/discord-service.ts`
- [Scrobbling](https://github.com/pear-devs/pear-desktop/tree/master/src/plugins/scrobbler): `src/plugins/scrobbler`
- [Discord service](https://github.com/pear-devs/pear-desktop/blob/master/src/plugins/discord/discord-service.ts): `src/plugins/discord/discord-service.ts`
- [Scrobble services](https://github.com/pear-devs/pear-desktop/tree/master/src/plugins/scrobbler/services): `src/plugins/scrobbler/services`

### Other components

- **Desktop user**
- **YouTube Music**

## Connections

- Desktop user → Electron shell: uses (evidence: `README.md`)
- YouTube Music → Electron shell: provides player
- Electron shell → Plugin lifecycle: loads plugins (evidence: `src/index.ts`)
- Plugin lifecycle → Plugin definitions: loads definitions (evidence: `src/loader/main.ts`)
- Plugin lifecycle → App configuration: reads settings (evidence: `src/loader/main.ts`)
- Plugin lifecycle → Plugin contexts: creates contexts (evidence: `src/loader/main.ts`)
- Desktop user → Native menus: configures features (evidence: `README.md`)
- Native menus → Plugin lifecycle: loads menu plugins (evidence: `src/menu.ts`)
- Player data bridge → Song metadata: sends player data (evidence: `src/providers/song-info-front.ts`)
- Electron shell → App controls: registers controls (evidence: `src/index.ts`)
- Control API → API routes: registers routes (evidence: `src/plugins/api-server/backend/main.ts`)
- API routes → Song controls: dispatches controls
- Plugin lifecycle → Control API: activates extension
- Plugin lifecycle → Synced lyrics: activates extension
- Plugin lifecycle → Shared listening: activates extension
- Plugin lifecycle → Music downloader: activates extension
- Plugin lifecycle → Audio enhancements: activates extension
- Plugin lifecycle → Rich presence: activates extension
- Plugin lifecycle → Scrobbling: activates extension
- Rich presence → Discord service: updates presence (evidence: `src/plugins/discord/main.ts`)
- Discord service → Song metadata: reads metadata (evidence: `src/plugins/discord/discord-service.ts`)
- Scrobbling → Scrobble services: uses services (evidence: `src/plugins/scrobbler/main.ts`)
