# ernani1234/musike architecture

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

- Interactive diagram: https://gitdiagram.com/ernani1234/musike
- Repository: https://github.com/ernani1234/musike

## Overview

Musike is a cross-platform personal music player. The main workflow is user search or browsing → catalog lookup → queue playback, with the server resolving and proxying streams for web/desktop; standalone mobile apps search and play directly from YouTube. The graph also preserves library, backup, video, radio, customization, and native playback capabilities. Edges use README statements and shown source references; mobile and some server internals are unsampled, so those links are documented or marked unverified rather than inferred from names.

Main entry points: [`server/src/app.ts`](https://github.com/ernani1234/musike/blob/main/server/src/app.ts) (REST API), [`mobile`](https://github.com/ernani1234/musike/tree/main/mobile) (Standalone mobile app), [`web/src/App.tsx`](https://github.com/ernani1234/musike/blob/main/web/src/App.tsx) (Web app shell), [`web/src/lib/api.ts`](https://github.com/ernani1234/musike/blob/main/web/src/lib/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Player clients"]
  node_desktop["Desktop shell<br/>[main.mts]"]
  node_mobile["Standalone mobile app"]
  node_androidplayback["Android playback"]
  node_iosplayback["iOS playback<br/>[MusikeAudio.swift]"]
end

subgraph group_web["Web experience"]
  node_webapp["Web app shell<br/>[App.tsx]"]
  node_catalogviews["Catalog views"]
  node_batchsearch["Batch search<br/>[BatchSearch.tsx]"]
  node_player["Queue player<br/>[player.ts]"]
  node_apiclient["API client<br/>[api.ts]"]
  node_libraryui["Library state<br/>[library.ts]"]
  node_preferences["Interface preferences<br/>[ui.ts]"]
end

subgraph group_server["Server services"]
  node_rest["REST API<br/>[app.ts]"]
  node_catalog["Catalog lookup<br/>[browse.ts]"]
  node_search["Search and video match<br/>[search.ts]"]
  node_streamresolve["Stream resolution<br/>[ytdlp.ts]"]
  node_streamproxy["Range stream proxy<br/>[stream.ts]"]
  node_libraryservice["Library service<br/>[library.ts]"]
  node_libraryfile[("Library file<br/>[libraryFile.ts]")]
  node_toolmanager["Tool maintenance<br/>[tools.ts]"]
end

subgraph group_media["Media providers"]
  node_ytmusic["YouTube Music"]
  node_youtube["YouTube media"]
end

node_listener(("Listener"))

node_listener -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_catalogviews
node_webapp -->|"uses"| node_player
node_webapp -->|"loads"| node_libraryui
node_webapp -->|"uses"| node_preferences
node_catalogviews -->|"requests"| node_apiclient
node_catalogviews -->|"routes to"| node_batchsearch
node_batchsearch -->|"searches"| node_apiclient
node_player -->|"prepares streams"| node_apiclient
node_player -->|"updates history"| node_libraryui
node_apiclient -->|"sends requests"| node_rest
node_listener -->|"uses"| node_desktop
node_desktop -->|"starts built-in server"| node_rest
node_listener -->|"uses"| node_mobile
node_mobile -.->|"supports playback"| node_androidplayback
node_mobile -.->|"supports playback"| node_iosplayback
node_rest -->|"routes catalog calls"| node_catalog
node_rest -->|"routes search"| node_search
node_rest -->|"handles library"| node_libraryservice
node_rest -->|"resolves playback"| node_streamresolve
node_rest -.->|"routes streaming"| node_streamproxy
node_rest -->|"configures storage"| node_libraryfile
node_rest -->|"refreshes tools"| node_toolmanager
node_catalog -->|"queries catalog"| node_ytmusic
node_search -->|"searches catalog"| node_ytmusic
node_streamresolve -->|"resolves media"| node_youtube
node_streamproxy -->|"proxies bytes"| node_youtube
node_libraryservice -->|"persists library"| node_libraryfile
node_mobile -.->|"searches directly"| node_ytmusic
node_mobile -.->|"plays directly"| node_youtube

click node_webapp "https://github.com/ernani1234/musike/blob/main/web/src/App.tsx"
click node_catalogviews "https://github.com/ernani1234/musike/tree/main/web/src/views"
click node_batchsearch "https://github.com/ernani1234/musike/blob/main/web/src/views/BatchSearch.tsx"
click node_player "https://github.com/ernani1234/musike/blob/main/web/src/player/player.ts"
click node_apiclient "https://github.com/ernani1234/musike/blob/main/web/src/lib/api.ts"
click node_libraryui "https://github.com/ernani1234/musike/blob/main/web/src/stores/library.ts"
click node_preferences "https://github.com/ernani1234/musike/blob/main/web/src/stores/ui.ts"
click node_desktop "https://github.com/ernani1234/musike/blob/main/desktop/src/main.mts"
click node_mobile "https://github.com/ernani1234/musike/tree/main/mobile"
click node_androidplayback "https://github.com/ernani1234/musike/blob/main/mobile/android/app/src/main/java/app/musike/android/PlaybackService.java"
click node_iosplayback "https://github.com/ernani1234/musike/blob/main/mobile/ios/App/App/MusikeAudio.swift"
click node_rest "https://github.com/ernani1234/musike/blob/main/server/src/app.ts"
click node_catalog "https://github.com/ernani1234/musike/blob/main/server/src/browse.ts"
click node_search "https://github.com/ernani1234/musike/blob/main/server/src/search.ts"
click node_streamresolve "https://github.com/ernani1234/musike/blob/main/server/src/ytdlp.ts"
click node_streamproxy "https://github.com/ernani1234/musike/blob/main/server/src/stream.ts"
click node_libraryservice "https://github.com/ernani1234/musike/blob/main/server/src/library.ts"
click node_libraryfile "https://github.com/ernani1234/musike/blob/main/server/src/libraryFile.ts"
click node_toolmanager "https://github.com/ernani1234/musike/blob/main/server/src/tools.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_desktop,node_mobile,node_androidplayback,node_iosplayback toneBlue
class node_webapp,node_catalogviews,node_batchsearch,node_player,node_apiclient,node_libraryui,node_preferences toneAmber
class node_rest,node_catalog,node_search,node_streamresolve,node_streamproxy,node_libraryservice,node_libraryfile,node_toolmanager toneMint
class node_ytmusic,node_youtube toneRose
class node_listener toneIndigo
```

## Components

### Player clients

- [Desktop shell](https://github.com/ernani1234/musike/blob/main/desktop/src/main.mts): `desktop/src/main.mts`
- [Standalone mobile app](https://github.com/ernani1234/musike/tree/main/mobile): `mobile`
- [Android playback](https://github.com/ernani1234/musike/blob/main/mobile/android/app/src/main/java/app/musike/android/PlaybackService.java): `mobile/android/app/src/main/java/app/musike/android/PlaybackService.java`
- [iOS playback](https://github.com/ernani1234/musike/blob/main/mobile/ios/App/App/MusikeAudio.swift): `mobile/ios/App/App/MusikeAudio.swift`

### Web experience

- [Web app shell](https://github.com/ernani1234/musike/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Catalog views](https://github.com/ernani1234/musike/tree/main/web/src/views): `web/src/views`
- [Batch search](https://github.com/ernani1234/musike/blob/main/web/src/views/BatchSearch.tsx): `web/src/views/BatchSearch.tsx`
- [Queue player](https://github.com/ernani1234/musike/blob/main/web/src/player/player.ts): `web/src/player/player.ts`
- [API client](https://github.com/ernani1234/musike/blob/main/web/src/lib/api.ts): `web/src/lib/api.ts`
- [Library state](https://github.com/ernani1234/musike/blob/main/web/src/stores/library.ts): `web/src/stores/library.ts`
- [Interface preferences](https://github.com/ernani1234/musike/blob/main/web/src/stores/ui.ts): `web/src/stores/ui.ts`

### Server services

- [REST API](https://github.com/ernani1234/musike/blob/main/server/src/app.ts): `server/src/app.ts`
- [Catalog lookup](https://github.com/ernani1234/musike/blob/main/server/src/browse.ts): `server/src/browse.ts`
- [Search and video match](https://github.com/ernani1234/musike/blob/main/server/src/search.ts): `server/src/search.ts`
- [Stream resolution](https://github.com/ernani1234/musike/blob/main/server/src/ytdlp.ts): `server/src/ytdlp.ts`
- [Range stream proxy](https://github.com/ernani1234/musike/blob/main/server/src/stream.ts): `server/src/stream.ts`
- [Library service](https://github.com/ernani1234/musike/blob/main/server/src/library.ts): `server/src/library.ts`
- [Library file](https://github.com/ernani1234/musike/blob/main/server/src/libraryFile.ts): `server/src/libraryFile.ts`
- [Tool maintenance](https://github.com/ernani1234/musike/blob/main/server/src/tools.ts): `server/src/tools.ts`

### Media providers

- **YouTube Music**
- **YouTube media**

### Other components

- **Listener**

## Connections

- Listener → Web app shell: uses
- Web app shell → Catalog views: routes to (evidence: `web/src/App.tsx`)
- Web app shell → Queue player: uses (evidence: `web/src/App.tsx`)
- Web app shell → Library state: loads (evidence: `web/src/App.tsx`)
- Web app shell → Interface preferences: uses (evidence: `web/src/App.tsx`)
- Catalog views → API client: requests (evidence: `web/src/views/BatchSearch.tsx`)
- Catalog views → Batch search: routes to (evidence: `web/src/App.tsx`)
- Batch search → API client: searches (evidence: `web/src/views/BatchSearch.tsx`)
- Queue player → API client: prepares streams (evidence: `web/src/player/player.ts`)
- Queue player → Library state: updates history (evidence: `web/src/player/player.ts`)
- API client → REST API: sends requests
- Listener → Desktop shell: uses
- Desktop shell → REST API: starts built-in server (evidence: `desktop/src/main.mts`)
- Listener → Standalone mobile app: uses
- Standalone mobile app → Android playback: supports playback (evidence: `mobile/android/app/src/main/java/app/musike/android/PlaybackService.java`)
- Standalone mobile app → iOS playback: supports playback (evidence: `mobile/ios/App/App/MusikeWebViewController.swift`)
- REST API → Catalog lookup: routes catalog calls (evidence: `server/src/app.ts`)
- REST API → Search and video match: routes search (evidence: `server/src/app.ts`)
- REST API → Library service: handles library (evidence: `server/src/app.ts`)
- REST API → Stream resolution: resolves playback (evidence: `server/src/app.ts`)
- REST API → Range stream proxy: routes streaming (evidence: `server/src/app.ts`)
- REST API → Library file: configures storage (evidence: `server/src/app.ts`)
- REST API → Tool maintenance: refreshes tools (evidence: `server/src/app.ts`)
- Catalog lookup → YouTube Music: queries catalog
- Search and video match → YouTube Music: searches catalog
- Stream resolution → YouTube media: resolves media
- Range stream proxy → YouTube media: proxies bytes
- Library service → Library file: persists library (evidence: `server/src/app.ts`)
- Standalone mobile app → YouTube Music: searches directly
- Standalone mobile app → YouTube media: plays directly