# vi-en/cachymusic architecture

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

- Interactive diagram: https://gitdiagram.com/vi-en/cachymusic
- Repository: https://github.com/vi-en/cachymusic

## Overview

CachyMusic is a cross-platform music player and browser-based audio workstation. The main workflow is importing or scanning music, reading tags and artwork, managing a library and playlists, then playing tracks through the audio engine with DSP and visualizations. Optional branches provide PHP-backed storage and media APIs, Soulseek sharing, offline PWA support, and desktop or Android playback integrations. Arrows reflect README statements and shown imports/calls; unsampled endpoint and native integration details are kept broad rather than inferred.

Main entry points: [`scripts/modules/app.js`](https://github.com/vi-en/cachymusic/blob/main/scripts/modules/app.js) (Workstation App), [`scripts/modules/library.js`](https://github.com/vi-en/cachymusic/blob/main/scripts/modules/library.js) (Music Library), [`php/database.php`](https://github.com/vi-en/cachymusic/blob/main/php/database.php) (Database Connector), [`scripts/modules/player-core.js`](https://github.com/vi-en/cachymusic/blob/main/scripts/modules/player-core.js) (Player Transport)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workstation["Player Workstation"]
  node_app["Workstation App<br/>[app.js]"]
  node_state["Workstation State<br/>[state.js]"]
  node_ui["Workspace UI<br/>[ui-elements.js]"]
  node_player["Player Transport<br/>[player-core.js]"]
  node_audio["Audio Engine DSP<br/>[audio-engine.js]"]
  node_dsp["AudioWorklet DSP"]
  node_visualizer["Visualizer<br/>[visualizer.js]"]
end

subgraph group_media["Library and Media"]
  node_library["Music Library<br/>[library.js]"]
  node_tagparser["Tag Parser<br/>[tag-parser.js]"]
  node_localdb[("Local Library Storage<br/>[local-library.js]")]
  node_lyrics["Lyrics<br/>[lyrics.js]"]
end

subgraph group_backend["PHP Host"]
  node_phpapi["Media API"]
  node_scan["Folder Scan<br/>[scan.php]"]
  node_stream["Track Streaming<br/>[stream.php]"]
  node_metadata["Metadata and Cover API<br/>[metadata.php]"]
  node_storage[("Host Storage<br/>[storage.php]")]
  node_database["Database Connector<br/>[database.php]"]
  node_platform["Platform Helpers<br/>[platform.php]"]
end

subgraph group_integrations["Platform Integrations"]
  node_p2p["P2P and Soulseek<br/>[p2p.js]"]
  node_soulseekapi["Soulseek API<br/>[soulseek.php]"]
  node_mpris["Linux MPRIS"]
  node_android["Android Activity<br/>[MainActivity.java]"]
  node_androidservice["Android Playback Service"]
end

subgraph group_offline["Offline PWA"]
  node_serviceworker["Offline Cache<br/>[sw.js]"]
  node_browser["Browser PWA<br/>[index.php]"]
end

node_listener(("Listener"))

node_listener -->|"uses"| node_app
node_app -->|"imports"| node_state
node_app -->|"imports"| node_ui
node_app -->|"imports"| node_player
node_app -->|"imports"| node_library
node_app -->|"imports"| node_audio
node_app -->|"imports"| node_visualizer
node_app -->|"imports"| node_lyrics
node_app -->|"imports"| node_p2p
node_library -->|"parses tags"| node_tagparser
node_library -->|"loads and saves"| node_localdb
node_library -->|"loads tracks"| node_player
node_library -->|"updates display"| node_lyrics
node_player -->|"configures routing"| node_audio
node_player -->|"updates display"| node_lyrics
node_audio -.->|"DSP capability"| node_dsp
node_listener -->|"requests scan"| node_scan
node_scan -->|"uses"| node_database
node_stream -->|"reads tracks"| node_database
node_metadata -->|"uses"| node_database
node_database -->|"loads helpers"| node_platform
node_database -->|"initializes"| node_storage
node_phpapi -.->|"includes"| node_scan
node_listener -->|"uses sharing"| node_p2p
node_p2p -.->|"optional backend"| node_soulseekapi
node_listener -->|"controls playback"| node_mpris
node_listener -->|"uses app"| node_android
node_android -->|"starts and controls"| node_androidservice
node_androidservice -->|"dispatches commands"| node_android
node_browser -->|"offline caching"| node_serviceworker

click node_app "https://github.com/vi-en/cachymusic/blob/main/scripts/modules/app.js"
click node_state "https://github.com/vi-en/cachymusic/blob/main/scripts/modules/state.js"
click node_ui "https://github.com/vi-en/cachymusic/blob/main/scripts/modules/ui-elements.js"
click node_player "https://github.com/vi-en/cachymusic/blob/main/scripts/modules/player-core.js"
click node_audio "https://github.com/vi-en/cachymusic/blob/main/scripts/modules/audio-engine.js"
click node_dsp "https://github.com/vi-en/cachymusic/blob/main/scripts/dsp-worklet-processor.js"
click node_visualizer "https://github.com/vi-en/cachymusic/blob/main/scripts/modules/visualizer.js"
click node_library "https://github.com/vi-en/cachymusic/blob/main/scripts/modules/library.js"
click node_tagparser "https://github.com/vi-en/cachymusic/blob/main/scripts/modules/tag-parser.js"
click node_localdb "https://github.com/vi-en/cachymusic/blob/main/scripts/modules/local-library.js"
click node_lyrics "https://github.com/vi-en/cachymusic/blob/main/scripts/modules/lyrics.js"
click node_phpapi "https://github.com/vi-en/cachymusic/tree/main/php/api"
click node_scan "https://github.com/vi-en/cachymusic/blob/main/php/api/scan.php"
click node_stream "https://github.com/vi-en/cachymusic/blob/main/php/api/stream.php"
click node_metadata "https://github.com/vi-en/cachymusic/blob/main/php/api/metadata.php"
click node_storage "https://github.com/vi-en/cachymusic/blob/main/php/storage.php"
click node_database "https://github.com/vi-en/cachymusic/blob/main/php/database.php"
click node_platform "https://github.com/vi-en/cachymusic/blob/main/php/platform.php"
click node_p2p "https://github.com/vi-en/cachymusic/blob/main/scripts/modules/p2p.js"
click node_soulseekapi "https://github.com/vi-en/cachymusic/blob/main/php/api/soulseek.php"
click node_mpris "https://github.com/vi-en/cachymusic/blob/main/bin/cachymusic-mpris.py"
click node_android "https://github.com/vi-en/cachymusic/blob/main/tools/packager/android/app/src/main/java/org/cachymusic/app/MainActivity.java"
click node_androidservice "https://github.com/vi-en/cachymusic/blob/main/tools/packager/android/app/src/main/java/org/cachymusic/app/MediaPlaybackService.java"
click node_serviceworker "https://github.com/vi-en/cachymusic/blob/main/sw.js"
click node_browser "https://github.com/vi-en/cachymusic/blob/main/index.php"

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_state,node_ui,node_player,node_audio,node_dsp,node_visualizer toneBlue
class node_library,node_tagparser,node_localdb,node_lyrics toneAmber
class node_phpapi,node_scan,node_stream,node_metadata,node_storage,node_database,node_platform toneMint
class node_p2p,node_soulseekapi,node_mpris,node_android,node_androidservice toneRose
class node_serviceworker,node_browser,node_listener toneIndigo
```

## Components

### Player Workstation

- [Workstation App](https://github.com/vi-en/cachymusic/blob/main/scripts/modules/app.js): `scripts/modules/app.js`
- [Workstation State](https://github.com/vi-en/cachymusic/blob/main/scripts/modules/state.js): `scripts/modules/state.js`
- [Workspace UI](https://github.com/vi-en/cachymusic/blob/main/scripts/modules/ui-elements.js): `scripts/modules/ui-elements.js`
- [Player Transport](https://github.com/vi-en/cachymusic/blob/main/scripts/modules/player-core.js): `scripts/modules/player-core.js`
- [Audio Engine DSP](https://github.com/vi-en/cachymusic/blob/main/scripts/modules/audio-engine.js): `scripts/modules/audio-engine.js`
- [AudioWorklet DSP](https://github.com/vi-en/cachymusic/blob/main/scripts/dsp-worklet-processor.js): `scripts/dsp-worklet-processor.js`
- [Visualizer](https://github.com/vi-en/cachymusic/blob/main/scripts/modules/visualizer.js): `scripts/modules/visualizer.js`

### Library and Media

- [Music Library](https://github.com/vi-en/cachymusic/blob/main/scripts/modules/library.js): `scripts/modules/library.js`
- [Tag Parser](https://github.com/vi-en/cachymusic/blob/main/scripts/modules/tag-parser.js): `scripts/modules/tag-parser.js`
- [Local Library Storage](https://github.com/vi-en/cachymusic/blob/main/scripts/modules/local-library.js): `scripts/modules/local-library.js`
- [Lyrics](https://github.com/vi-en/cachymusic/blob/main/scripts/modules/lyrics.js): `scripts/modules/lyrics.js`

### PHP Host

- [Media API](https://github.com/vi-en/cachymusic/tree/main/php/api): `php/api`
- [Folder Scan](https://github.com/vi-en/cachymusic/blob/main/php/api/scan.php): `php/api/scan.php`
- [Track Streaming](https://github.com/vi-en/cachymusic/blob/main/php/api/stream.php): `php/api/stream.php`
- [Metadata and Cover API](https://github.com/vi-en/cachymusic/blob/main/php/api/metadata.php): `php/api/metadata.php`
- [Host Storage](https://github.com/vi-en/cachymusic/blob/main/php/storage.php): `php/storage.php`
- [Database Connector](https://github.com/vi-en/cachymusic/blob/main/php/database.php): `php/database.php`
- [Platform Helpers](https://github.com/vi-en/cachymusic/blob/main/php/platform.php): `php/platform.php`

### Platform Integrations

- [P2P and Soulseek](https://github.com/vi-en/cachymusic/blob/main/scripts/modules/p2p.js): `scripts/modules/p2p.js`
- [Soulseek API](https://github.com/vi-en/cachymusic/blob/main/php/api/soulseek.php): `php/api/soulseek.php`
- [Linux MPRIS](https://github.com/vi-en/cachymusic/blob/main/bin/cachymusic-mpris.py): `bin/cachymusic-mpris.py`
- [Android Activity](https://github.com/vi-en/cachymusic/blob/main/tools/packager/android/app/src/main/java/org/cachymusic/app/MainActivity.java): `tools/packager/android/app/src/main/java/org/cachymusic/app/MainActivity.java`
- [Android Playback Service](https://github.com/vi-en/cachymusic/blob/main/tools/packager/android/app/src/main/java/org/cachymusic/app/MediaPlaybackService.java): `tools/packager/android/app/src/main/java/org/cachymusic/app/MediaPlaybackService.java`

### Offline PWA

- [Offline Cache](https://github.com/vi-en/cachymusic/blob/main/sw.js): `sw.js`
- [Browser PWA](https://github.com/vi-en/cachymusic/blob/main/index.php): `index.php`

### Other components

- **Listener**

## Connections

- Listener → Workstation App: uses (evidence: `README.md`)
- Workstation App → Workstation State: imports (evidence: `scripts/modules/app.js`)
- Workstation App → Workspace UI: imports (evidence: `scripts/modules/app.js`)
- Workstation App → Player Transport: imports (evidence: `scripts/modules/app.js`)
- Workstation App → Music Library: imports (evidence: `scripts/modules/app.js`)
- Workstation App → Audio Engine DSP: imports (evidence: `scripts/modules/app.js`)
- Workstation App → Visualizer: imports (evidence: `scripts/modules/app.js`)
- Workstation App → Lyrics: imports (evidence: `scripts/modules/app.js`)
- Workstation App → P2P and Soulseek: imports (evidence: `scripts/modules/app.js`)
- Music Library → Tag Parser: parses tags (evidence: `scripts/modules/library.js`)
- Music Library → Local Library Storage: loads and saves (evidence: `scripts/modules/library.js`)
- Music Library → Player Transport: loads tracks (evidence: `scripts/modules/library.js`)
- Music Library → Lyrics: updates display (evidence: `scripts/modules/library.js`)
- Player Transport → Audio Engine DSP: configures routing (evidence: `scripts/modules/player-core.js`)
- Player Transport → Lyrics: updates display (evidence: `scripts/modules/player-core.js`)
- Audio Engine DSP → AudioWorklet DSP: DSP capability (evidence: `README.md`)
- Listener → Folder Scan: requests scan (evidence: `README.md`)
- Folder Scan → Database Connector: uses (evidence: `php/api/scan.php`)
- Track Streaming → Database Connector: reads tracks (evidence: `php/api/stream.php`)
- Metadata and Cover API → Database Connector: uses (evidence: `php/api/metadata.php`)
- Database Connector → Platform Helpers: loads helpers (evidence: `php/database.php`)
- Database Connector → Host Storage: initializes (evidence: `php/database.php`)
- Media API → Folder Scan: includes (evidence: `php/api/soulseek.php`)
- Listener → P2P and Soulseek: uses sharing (evidence: `README.md`)
- P2P and Soulseek → Soulseek API: optional backend
- Listener → Linux MPRIS: controls playback (evidence: `README.md`)
- Listener → Android Activity: uses app (evidence: `README.md`)
- Android Activity → Android Playback Service: starts and controls (evidence: `tools/packager/android/app/src/main/java/org/cachymusic/app/MainActivity.java`)
- Android Playback Service → Android Activity: dispatches commands (evidence: `tools/packager/android/app/src/main/java/org/cachymusic/app/MediaPlaybackService.java`)
- Browser PWA → Offline Cache: offline caching (evidence: `README.md`)
