# aftaaab/cupid-music-player architecture

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

- Interactive diagram: https://gitdiagram.com/aftaaab/cupid-music-player
- Repository: https://github.com/aftaaab/cupid-music-player

## Overview

Cupid Music Player is a themed music player spanning a React interface in Electron and an Android WebView. Users choose local music or browse Spotify, Apple Music, or YouTube playlists, then control playback in the player. Spotify metadata is paired with YouTube audio streaming through the Electron process; local playback uses HTML5 Audio. The graph also shows the documented Android song library and native media controls. Some runtime source was only sampled, so uncertain subsystem wiring is omitted.

Main entry points: [`src/App.jsx`](https://github.com/aftaaab/cupid-music-player/blob/main/src/App.jsx) (Player app), [`electron/preload.cjs`](https://github.com/aftaaab/cupid-music-player/blob/main/electron/preload.cjs) (Desktop bridge), [`electron/main.cjs`](https://github.com/aftaaab/cupid-music-player/blob/main/electron/main.cjs) (Desktop main process), [`src/useAudioPlayer.js`](https://github.com/aftaaab/cupid-music-player/blob/main/src/useAudioPlayer.js) (Local playback)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Player interface"]
  node_app["Player app<br/>[App.jsx]"]
  node_theme["Themes and animation<br/>[useTheme.js]"]
  node_localplayer["Local playback<br/>[useAudioPlayer.js]"]
  node_streamplayer["Stream playback"]
end

subgraph group_sources["Music sources"]
  node_localfiles["Local playlist and audio<br/>[playlist.json]"]
  node_spotifyauth["Spotify sign-in<br/>[auth.js]"]
  node_spotifyapi["Spotify playlists<br/>[api.js]"]
  node_appleauth["Apple Music sign-in<br/>[auth.js]"]
  node_appleapi["Apple Music library<br/>[api.js]"]
  node_youtubeapi["YouTube playlists<br/>[api.js]"]
  node_youtubeauth["Google sign-in<br/>[auth.js]"]
end

subgraph group_desktop["Desktop runtime"]
  node_electron["Desktop main process<br/>[main.cjs]"]
  node_preload["Desktop bridge<br/>[preload.cjs]"]
  node_stream["Audio stream resolver<br/>[main.cjs]"]
  node_desktopaudio[("Desktop audio files")]
end

subgraph group_mobile["Android runtime"]
  node_shim["Mobile platform bridge<br/>[shim.js]"]
  node_library["On-device library<br/>[library.js]"]
  node_android["Android media controls<br/>[MainActivity.java]"]
end

node_listener(("Listener"))
node_spotify{{"Spotify API"}}
node_musickit{{"MusicKit JS"}}
node_youtube{{"YouTube services"}}
node_ytdlp["yt-dlp"]
node_capacitor[("Capacitor filesystem")]

node_listener -->|"uses"| node_app
node_app -->|"selects theme"| node_theme
node_app -->|"controls local"| node_localplayer
node_app -->|"controls streaming"| node_streamplayer
node_app -->|"signs in"| node_spotifyauth
node_app -->|"loads playlists"| node_spotifyapi
node_spotifyauth -->|"requests tokens"| node_spotify
node_spotifyapi -->|"fetches playlists"| node_spotify
node_app -->|"signs in"| node_appleauth
node_app -->|"loads playlists"| node_appleapi
node_appleauth -->|"authorizes"| node_musickit
node_appleapi -->|"fetches library"| node_musickit
node_app -->|"loads playlists"| node_youtubeapi
node_app -->|"signs in"| node_youtubeauth
node_youtubeapi -->|"fetches playlists"| node_youtube
node_youtubeauth -->|"requests tokens"| node_youtube
node_localplayer -->|"resolves local audio"| node_preload
node_localplayer -->|"reads playlist"| node_localfiles
node_app -->|"requests local playlist"| node_preload
node_preload -->|"forwards requests"| node_electron
node_electron -->|"reads files"| node_desktopaudio
node_streamplayer -->|"requests stream"| node_preload
node_preload -->|"forwards requests"| node_electron
node_electron -->|"resolves audio"| node_stream
node_stream -->|"extracts stream URL"| node_ytdlp
node_streamplayer -.->|"plays YouTube audio"| node_youtube
node_app -->|"uses mobile bridge"| node_shim
node_shim -->|"loads added songs"| node_library
node_library -->|"reads and writes"| node_capacitor
node_android -->|"dispatches media controls"| node_app
node_app -->|"updates playback metadata"| node_android

click node_app "https://github.com/aftaaab/cupid-music-player/blob/main/src/App.jsx"
click node_theme "https://github.com/aftaaab/cupid-music-player/blob/main/src/useTheme.js"
click node_localplayer "https://github.com/aftaaab/cupid-music-player/blob/main/src/useAudioPlayer.js"
click node_streamplayer "https://github.com/aftaaab/cupid-music-player/blob/main/src/useSpotifyPlayer.js"
click node_localfiles "https://github.com/aftaaab/cupid-music-player/blob/main/audio/playlist.json"
click node_spotifyauth "https://github.com/aftaaab/cupid-music-player/blob/main/src/spotify/auth.js"
click node_spotifyapi "https://github.com/aftaaab/cupid-music-player/blob/main/src/spotify/api.js"
click node_appleauth "https://github.com/aftaaab/cupid-music-player/blob/main/src/apple/auth.js"
click node_appleapi "https://github.com/aftaaab/cupid-music-player/blob/main/src/apple/api.js"
click node_youtubeapi "https://github.com/aftaaab/cupid-music-player/blob/main/src/youtube/api.js"
click node_youtubeauth "https://github.com/aftaaab/cupid-music-player/blob/main/src/youtube/auth.js"
click node_electron "https://github.com/aftaaab/cupid-music-player/blob/main/electron/main.cjs"
click node_preload "https://github.com/aftaaab/cupid-music-player/blob/main/electron/preload.cjs"
click node_stream "https://github.com/aftaaab/cupid-music-player/blob/main/electron/main.cjs"
click node_desktopaudio "https://github.com/aftaaab/cupid-music-player/tree/main/audio"
click node_shim "https://github.com/aftaaab/cupid-music-player/blob/main/src/mobile/shim.js"
click node_library "https://github.com/aftaaab/cupid-music-player/blob/main/src/mobile/library.js"
click node_android "https://github.com/aftaaab/cupid-music-player/blob/main/android/app/src/main/java/com/cupid/player/MainActivity.java"

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_theme,node_localplayer,node_streamplayer toneBlue
class node_localfiles,node_spotifyauth,node_spotifyapi,node_appleauth,node_appleapi,node_youtubeapi,node_youtubeauth,node_capacitor toneAmber
class node_electron,node_preload,node_stream,node_desktopaudio,node_spotify toneMint
class node_shim,node_library,node_android toneRose
class node_listener,node_musickit,node_youtube,node_ytdlp toneIndigo
```

## Components

### Player interface

- [Player app](https://github.com/aftaaab/cupid-music-player/blob/main/src/App.jsx): `src/App.jsx`
- [Themes and animation](https://github.com/aftaaab/cupid-music-player/blob/main/src/useTheme.js): `src/useTheme.js`
- [Local playback](https://github.com/aftaaab/cupid-music-player/blob/main/src/useAudioPlayer.js): `src/useAudioPlayer.js`
- [Stream playback](https://github.com/aftaaab/cupid-music-player/blob/main/src/useSpotifyPlayer.js): `src/useSpotifyPlayer.js`

### Music sources

- [Local playlist and audio](https://github.com/aftaaab/cupid-music-player/blob/main/audio/playlist.json): `audio/playlist.json`
- [Spotify sign-in](https://github.com/aftaaab/cupid-music-player/blob/main/src/spotify/auth.js): `src/spotify/auth.js`
- [Spotify playlists](https://github.com/aftaaab/cupid-music-player/blob/main/src/spotify/api.js): `src/spotify/api.js`
- [Apple Music sign-in](https://github.com/aftaaab/cupid-music-player/blob/main/src/apple/auth.js): `src/apple/auth.js`
- [Apple Music library](https://github.com/aftaaab/cupid-music-player/blob/main/src/apple/api.js): `src/apple/api.js`
- [YouTube playlists](https://github.com/aftaaab/cupid-music-player/blob/main/src/youtube/api.js): `src/youtube/api.js`
- [Google sign-in](https://github.com/aftaaab/cupid-music-player/blob/main/src/youtube/auth.js): `src/youtube/auth.js`

### Desktop runtime

- [Desktop main process](https://github.com/aftaaab/cupid-music-player/blob/main/electron/main.cjs): `electron/main.cjs`
- [Desktop bridge](https://github.com/aftaaab/cupid-music-player/blob/main/electron/preload.cjs): `electron/preload.cjs`
- [Audio stream resolver](https://github.com/aftaaab/cupid-music-player/blob/main/electron/main.cjs): `electron/main.cjs`
- [Desktop audio files](https://github.com/aftaaab/cupid-music-player/tree/main/audio): `audio`

### Android runtime

- [Mobile platform bridge](https://github.com/aftaaab/cupid-music-player/blob/main/src/mobile/shim.js): `src/mobile/shim.js`
- [On-device library](https://github.com/aftaaab/cupid-music-player/blob/main/src/mobile/library.js): `src/mobile/library.js`
- [Android media controls](https://github.com/aftaaab/cupid-music-player/blob/main/android/app/src/main/java/com/cupid/player/MainActivity.java): `android/app/src/main/java/com/cupid/player/MainActivity.java`

### Other components

- **Listener**
- **Spotify API**
- **MusicKit JS**
- **YouTube services**
- **yt-dlp**
- **Capacitor filesystem**

## Connections

- Listener → Player app: uses
- Player app → Themes and animation: selects theme
- Player app → Local playback: controls local
- Player app → Stream playback: controls streaming
- Player app → Spotify sign-in: signs in
- Player app → Spotify playlists: loads playlists
- Spotify sign-in → Spotify API: requests tokens
- Spotify playlists → Spotify API: fetches playlists
- Player app → Apple Music sign-in: signs in
- Player app → Apple Music library: loads playlists
- Apple Music sign-in → MusicKit JS: authorizes
- Apple Music library → MusicKit JS: fetches library
- Player app → YouTube playlists: loads playlists
- Player app → Google sign-in: signs in
- YouTube playlists → YouTube services: fetches playlists
- Google sign-in → YouTube services: requests tokens
- Local playback → Desktop bridge: resolves local audio
- Local playback → Local playlist and audio: reads playlist
- Player app → Desktop bridge: requests local playlist
- Desktop bridge → Desktop main process: forwards requests
- Desktop main process → Desktop audio files: reads files
- Stream playback → Desktop bridge: requests stream
- Desktop bridge → Desktop main process: forwards requests
- Desktop main process → Audio stream resolver: resolves audio
- Audio stream resolver → yt-dlp: extracts stream URL
- Stream playback → YouTube services: plays YouTube audio
- Player app → Mobile platform bridge: uses mobile bridge
- Mobile platform bridge → On-device library: loads added songs
- On-device library → Capacitor filesystem: reads and writes
- Android media controls → Player app: dispatches media controls
- Player app → Android media controls: updates playback metadata