# derpycat306/music_player architecture

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

- Interactive diagram: https://gitdiagram.com/derpycat306/music_player
- Repository: https://github.com/derpycat306/music_player

## Overview

This is an Electron desktop player for a locally owned music library. The user selects a library folder, browses artists, albums, playlists, or filtered songs, and plays tracks with persistent playback controls; favorites and playlists extend that workflow. Electron provides local-file access, saved settings, and update handling, while the React renderer owns browsing and playback interfaces. README capabilities include live library updates and folder-based artwork; sampled evidence does not expose all renderer-to-Electron wiring, so uncertain links are omitted.

Main entry points: [`src/ui/App/App.tsx`](https://github.com/derpycat306/music_player/blob/main/src/ui/App/App.tsx) (React application), [`src/ui/Pages/Main/MainWindow.tsx`](https://github.com/derpycat306/music_player/blob/main/src/ui/Pages/Main/MainWindow.tsx) (Main window), [`src/electron/main.ts`](https://github.com/derpycat306/music_player/blob/main/src/electron/main.ts) (Desktop lifecycle), [`src/ui/AudioPlayer/AudioPlayerProvider.tsx`](https://github.com/derpycat306/music_player/blob/main/src/ui/AudioPlayer/AudioPlayerProvider.tsx) (Player state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Electron runtime"]
  node_electron["Desktop lifecycle<br/>[main.ts]"]
  node_reader["Folder discovery"]
  node_extensions["Audio extensions"]
  node_protocol["Music protocol<br/>[requestProtocol.ts]"]
  node_persistence[("Saved data<br/>[saveHandler.ts]")]
  node_preload["Renderer bridge<br/>[preload.cts]"]
  node_updates["Release updates<br/>[main.ts]"]
end

subgraph group_library["Library and navigation"]
  node_explorer["Library state"]
  node_filetree["Folder browser<br/>[FileExplorer.tsx]"]
  node_header["Library navigation<br/>[MainHeader.tsx]"]
  node_panel["Browse and detail<br/>[MainPanel.tsx]"]
  node_songlist["Song listing<br/>[SongList.tsx]"]
  node_virtual["List virtualization<br/>[useVirtualList.ts]"]
  node_artwork["Artwork resolution<br/>[artwork.ts]"]
end

subgraph group_playback["Playback and curation"]
  node_player["Player state"]
  node_playercontext["Player context"]
  node_playbar["Playback controls<br/>[PlayBar.tsx]"]
  node_songitem["Song actions<br/>[SongItem.tsx]"]
  node_songmenu["Favorite and playlist menu<br/>[SongContext.tsx]"]
  node_contextmenu["Context menu<br/>[ContextMenu.tsx]"]
end

subgraph group_interface["Application interface"]
  node_app["React application<br/>[App.tsx]"]
  node_mainwindow["Main window<br/>[MainWindow.tsx]"]
  node_settings["Settings screen<br/>[SettingsMenu.tsx]"]
end

node_user(("Listener"))
node_filesystem[("Local music files")]
node_upstream["Update service"]

node_electron -->|"initializes"| node_reader
node_electron -->|"initializes"| node_protocol
node_electron -->|"loads settings"| node_persistence
node_reader -->|"checks formats"| node_extensions
node_reader -->|"uses saved data"| node_persistence
node_protocol -.->|"serves local audio"| node_filesystem
node_electron -->|"handles update IPC"| node_updates
node_updates -->|"checks and downloads"| node_upstream
node_user -->|"uses"| node_app
node_app -->|"routes to"| node_mainwindow
node_app -->|"routes to"| node_settings
node_app -->|"provides"| node_explorer
node_app -->|"renders"| node_playbar
node_mainwindow -->|"renders"| node_filetree
node_mainwindow -->|"renders"| node_header
node_mainwindow -->|"renders"| node_panel
node_mainwindow -->|"renders"| node_songlist
node_explorer -->|"uses playback"| node_player
node_explorer -->|"resolves library art"| node_artwork
node_panel -->|"virtualizes tracks"| node_virtual
node_panel -->|"resolves display art"| node_artwork
node_songlist -->|"virtualizes rows"| node_virtual
node_playbar -->|"reads controls"| node_player
node_songitem -->|"uses player state"| node_player
node_songitem -->|"opens actions"| node_songmenu
node_songmenu -->|"updates favorites"| node_player
node_songmenu -->|"renders"| node_contextmenu
node_player -->|"provides context"| node_playercontext
node_preload -.->|"bridges IPC"| node_electron
node_settings -.->|"reads and writes settings"| node_persistence
node_reader -.->|"discovers local songs"| node_filesystem

click node_electron "https://github.com/derpycat306/music_player/blob/main/src/electron/main.ts"
click node_reader "https://github.com/derpycat306/music_player/blob/main/src/electron/songFolderReader.ts"
click node_extensions "https://github.com/derpycat306/music_player/blob/main/src/electron/extentionHandler.ts"
click node_protocol "https://github.com/derpycat306/music_player/blob/main/src/electron/requestProtocol.ts"
click node_persistence "https://github.com/derpycat306/music_player/blob/main/src/electron/saveHandler.ts"
click node_preload "https://github.com/derpycat306/music_player/blob/main/src/electron/preload.cts"
click node_updates "https://github.com/derpycat306/music_player/blob/main/src/electron/main.ts"
click node_app "https://github.com/derpycat306/music_player/blob/main/src/ui/App/App.tsx"
click node_mainwindow "https://github.com/derpycat306/music_player/blob/main/src/ui/Pages/Main/MainWindow.tsx"
click node_settings "https://github.com/derpycat306/music_player/blob/main/src/ui/Pages/Settings/SettingsMenu.tsx"
click node_explorer "https://github.com/derpycat306/music_player/blob/main/src/ui/Pages/Main/ExplorerContext/ExplorerProvider.tsx"
click node_filetree "https://github.com/derpycat306/music_player/blob/main/src/ui/Pages/Main/FileExplorer/FileExplorer.tsx"
click node_header "https://github.com/derpycat306/music_player/blob/main/src/ui/Pages/Main/Header/MainHeader.tsx"
click node_panel "https://github.com/derpycat306/music_player/blob/main/src/ui/Pages/Main/MainPanel/MainPanel.tsx"
click node_songlist "https://github.com/derpycat306/music_player/blob/main/src/ui/Pages/Main/SongListing/Songs/SongList.tsx"
click node_virtual "https://github.com/derpycat306/music_player/blob/main/src/ui/Pages/Main/useVirtualList.ts"
click node_artwork "https://github.com/derpycat306/music_player/blob/main/src/ui/artwork.ts"
click node_player "https://github.com/derpycat306/music_player/blob/main/src/ui/AudioPlayer/AudioPlayerProvider.tsx"
click node_playercontext "https://github.com/derpycat306/music_player/blob/main/src/ui/AudioPlayer/AudioPlayerContext.tsx"
click node_playbar "https://github.com/derpycat306/music_player/blob/main/src/ui/PlayBar/PlayBar.tsx"
click node_songitem "https://github.com/derpycat306/music_player/blob/main/src/ui/Pages/Main/SongListing/Songs/Item/SongItem.tsx"
click node_songmenu "https://github.com/derpycat306/music_player/blob/main/src/ui/Pages/Main/SongListing/Songs/Item/SongContext.tsx"
click node_contextmenu "https://github.com/derpycat306/music_player/blob/main/src/ui/ContextMenu/ContextMenu.tsx"

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_electron,node_reader,node_extensions,node_protocol,node_persistence,node_preload,node_updates toneBlue
class node_explorer,node_filetree,node_header,node_panel,node_songlist,node_virtual,node_artwork,node_filesystem toneAmber
class node_player,node_playercontext,node_playbar,node_songitem,node_songmenu,node_contextmenu toneMint
class node_app,node_mainwindow,node_settings toneRose
class node_user,node_upstream toneIndigo
```

## Components

### Electron runtime

- [Desktop lifecycle](https://github.com/derpycat306/music_player/blob/main/src/electron/main.ts): `src/electron/main.ts`
- [Folder discovery](https://github.com/derpycat306/music_player/blob/main/src/electron/songFolderReader.ts): `src/electron/songFolderReader.ts`
- [Audio extensions](https://github.com/derpycat306/music_player/blob/main/src/electron/extentionHandler.ts): `src/electron/extentionHandler.ts`
- [Music protocol](https://github.com/derpycat306/music_player/blob/main/src/electron/requestProtocol.ts): `src/electron/requestProtocol.ts`
- [Saved data](https://github.com/derpycat306/music_player/blob/main/src/electron/saveHandler.ts): `src/electron/saveHandler.ts`
- [Renderer bridge](https://github.com/derpycat306/music_player/blob/main/src/electron/preload.cts): `src/electron/preload.cts`
- [Release updates](https://github.com/derpycat306/music_player/blob/main/src/electron/main.ts): `src/electron/main.ts`

### Library and navigation

- [Library state](https://github.com/derpycat306/music_player/blob/main/src/ui/Pages/Main/ExplorerContext/ExplorerProvider.tsx): `src/ui/Pages/Main/ExplorerContext/ExplorerProvider.tsx`
- [Folder browser](https://github.com/derpycat306/music_player/blob/main/src/ui/Pages/Main/FileExplorer/FileExplorer.tsx): `src/ui/Pages/Main/FileExplorer/FileExplorer.tsx`
- [Library navigation](https://github.com/derpycat306/music_player/blob/main/src/ui/Pages/Main/Header/MainHeader.tsx): `src/ui/Pages/Main/Header/MainHeader.tsx`
- [Browse and detail](https://github.com/derpycat306/music_player/blob/main/src/ui/Pages/Main/MainPanel/MainPanel.tsx): `src/ui/Pages/Main/MainPanel/MainPanel.tsx`
- [Song listing](https://github.com/derpycat306/music_player/blob/main/src/ui/Pages/Main/SongListing/Songs/SongList.tsx): `src/ui/Pages/Main/SongListing/Songs/SongList.tsx`
- [List virtualization](https://github.com/derpycat306/music_player/blob/main/src/ui/Pages/Main/useVirtualList.ts): `src/ui/Pages/Main/useVirtualList.ts`
- [Artwork resolution](https://github.com/derpycat306/music_player/blob/main/src/ui/artwork.ts): `src/ui/artwork.ts`

### Playback and curation

- [Player state](https://github.com/derpycat306/music_player/blob/main/src/ui/AudioPlayer/AudioPlayerProvider.tsx): `src/ui/AudioPlayer/AudioPlayerProvider.tsx`
- [Player context](https://github.com/derpycat306/music_player/blob/main/src/ui/AudioPlayer/AudioPlayerContext.tsx): `src/ui/AudioPlayer/AudioPlayerContext.tsx`
- [Playback controls](https://github.com/derpycat306/music_player/blob/main/src/ui/PlayBar/PlayBar.tsx): `src/ui/PlayBar/PlayBar.tsx`
- [Song actions](https://github.com/derpycat306/music_player/blob/main/src/ui/Pages/Main/SongListing/Songs/Item/SongItem.tsx): `src/ui/Pages/Main/SongListing/Songs/Item/SongItem.tsx`
- [Favorite and playlist menu](https://github.com/derpycat306/music_player/blob/main/src/ui/Pages/Main/SongListing/Songs/Item/SongContext.tsx): `src/ui/Pages/Main/SongListing/Songs/Item/SongContext.tsx`
- [Context menu](https://github.com/derpycat306/music_player/blob/main/src/ui/ContextMenu/ContextMenu.tsx): `src/ui/ContextMenu/ContextMenu.tsx`

### Application interface

- [React application](https://github.com/derpycat306/music_player/blob/main/src/ui/App/App.tsx): `src/ui/App/App.tsx`
- [Main window](https://github.com/derpycat306/music_player/blob/main/src/ui/Pages/Main/MainWindow.tsx): `src/ui/Pages/Main/MainWindow.tsx`
- [Settings screen](https://github.com/derpycat306/music_player/blob/main/src/ui/Pages/Settings/SettingsMenu.tsx): `src/ui/Pages/Settings/SettingsMenu.tsx`

### Other components

- **Listener**
- **Local music files**
- **Update service**

## Connections

- Desktop lifecycle → Folder discovery: initializes (evidence: `src/electron/main.ts`)
- Desktop lifecycle → Music protocol: initializes (evidence: `src/electron/main.ts`)
- Desktop lifecycle → Saved data: loads settings (evidence: `src/electron/main.ts`)
- Folder discovery → Audio extensions: checks formats (evidence: `src/electron/songFolderReader.ts`)
- Folder discovery → Saved data: uses saved data (evidence: `src/electron/songFolderReader.ts`)
- Music protocol → Local music files: serves local audio
- Desktop lifecycle → Release updates: handles update IPC (evidence: `src/electron/main.ts`)
- Release updates → Update service: checks and downloads (evidence: `src/electron/main.ts`)
- Listener → React application: uses (evidence: `src/ui/App/App.tsx`)
- React application → Main window: routes to (evidence: `src/ui/App/App.tsx`)
- React application → Settings screen: routes to (evidence: `src/ui/App/App.tsx`)
- React application → Library state: provides (evidence: `src/ui/App/App.tsx`)
- React application → Playback controls: renders (evidence: `src/ui/App/App.tsx`)
- Main window → Folder browser: renders (evidence: `src/ui/Pages/Main/MainWindow.tsx`)
- Main window → Library navigation: renders (evidence: `src/ui/Pages/Main/MainWindow.tsx`)
- Main window → Browse and detail: renders (evidence: `src/ui/Pages/Main/MainWindow.tsx`)
- Main window → Song listing: renders (evidence: `src/ui/Pages/Main/MainWindow.tsx`)
- Library state → Player state: uses playback (evidence: `src/ui/Pages/Main/ExplorerContext/ExplorerProvider.tsx`)
- Library state → Artwork resolution: resolves library art (evidence: `src/ui/Pages/Main/ExplorerContext/ExplorerProvider.tsx`)
- Browse and detail → List virtualization: virtualizes tracks (evidence: `src/ui/Pages/Main/MainPanel/MainPanel.tsx`)
- Browse and detail → Artwork resolution: resolves display art (evidence: `src/ui/Pages/Main/MainPanel/MainPanel.tsx`)
- Song listing → List virtualization: virtualizes rows (evidence: `src/ui/Pages/Main/SongListing/Songs/SongList.tsx`)
- Playback controls → Player state: reads controls (evidence: `src/ui/PlayBar/PlayBar.tsx`)
- Song actions → Player state: uses player state (evidence: `src/ui/Pages/Main/SongListing/Songs/Item/SongItem.tsx`)
- Song actions → Favorite and playlist menu: opens actions (evidence: `src/ui/Pages/Main/SongListing/Songs/Item/SongItem.tsx`)
- Favorite and playlist menu → Player state: updates favorites (evidence: `src/ui/Pages/Main/SongListing/Songs/Item/SongContext.tsx`)
- Favorite and playlist menu → Context menu: renders (evidence: `src/ui/Pages/Main/SongListing/Songs/Item/SongContext.tsx`)
- Player state → Player context: provides context (evidence: `src/ui/AudioPlayer/AudioPlayerProvider.tsx`)
- Renderer bridge → Desktop lifecycle: bridges IPC
- Settings screen → Saved data: reads and writes settings
- Folder discovery → Local music files: discovers local songs
