# ralihachev/musicstation architecture

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

- Interactive diagram: https://gitdiagram.com/ralihachev/musicstation
- Repository: https://github.com/ralihachev/musicstation

## Overview

MusicStation is an ESP32-S3 music player with an e-paper interface. The documented V1 workflow shows iPhone playback metadata arriving over Bluetooth, online artwork and lyrics fetched over Wi-Fi, and a compact display rendered on e-paper. V2 shifts the workflow toward a microSD library, local playlists and sidecars, queue-based playback, and physical controls; its audio backend is currently simulated. V2 relationships below use sampled excerpts and the SOURCE INDEX where possible. The V1 branch reflects README documentation; unsampled V2 orchestration links are omitted or marked unverified.

Main entry points: [`V2/MusicStationV2/player.cpp`](https://github.com/ralihachev/musicstation/blob/main/V2/MusicStationV2/player.cpp) (Queue and playback), [`V2/MusicStationV2/ui.cpp`](https://github.com/ralihachev/musicstation/blob/main/V2/MusicStationV2/ui.cpp) (Navigation and UI), [`V2/MusicStationV2/library.cpp`](https://github.com/ralihachev/musicstation/blob/main/V2/MusicStationV2/library.cpp) (Music library index), [`MusicStation.ino`](https://github.com/ralihachev/musicstation/blob/main/MusicStation.ino) (V1 firmware)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_v1["V1 companion"]
  node_v1firmware["V1 firmware<br/>[MusicStation.ino]"]
  node_v1display["E-paper display"]
end

subgraph group_v2nav["V2 interaction"]
  node_controls["Button input<br/>[input.cpp]"]
  node_ui["Navigation and UI<br/>[ui.cpp]"]
  node_panel["E-paper panel<br/>[panel.cpp]"]
end

subgraph group_v2media["V2 media"]
  node_storage[("SD storage<br/>[storage.cpp]")]
  node_library["Music library index<br/>[library.cpp]"]
  node_metadata["MP3 metadata<br/>[mp3meta.cpp]"]
  node_playlists["Playlist handling<br/>[playlist.cpp]"]
  node_covers["Local artwork<br/>[cover.cpp]"]
  node_lyrics["Synchronized lyrics<br/>[lyrics.cpp]"]
end

subgraph group_v2runtime["V2 playback"]
  node_player["Queue and playback<br/>[player.cpp]"]
  node_audio["Audio backend<br/>[audio.cpp]"]
  node_settings[("Persistent state<br/>[settings.cpp]")]
end

subgraph group_v2device["V2 device"]
  node_power["Power management<br/>[power.cpp]"]
end

node_phone(("iPhone"))
node_online["Online services"]

node_phone -->|"sends playback state"| node_v1firmware
node_online -->|"provides artwork and lyrics"| node_v1firmware
node_v1firmware -->|"renders player screen"| node_v1display
node_controls -.->|"dispatches input"| node_ui
node_ui -->|"controls playback"| node_player
node_ui -->|"reads browse records"| node_library
node_ui -->|"updates settings"| node_settings
node_ui -->|"refreshes playlists"| node_playlists
node_ui -.->|"draws screens"| node_panel
node_library -->|"probes track metadata"| node_metadata
node_library -->|"reads and writes index"| node_storage
node_playlists -.->|"reads playlist files"| node_storage
node_player -->|"builds track queues"| node_library
node_player -->|"loads playlist queue"| node_playlists
node_player -->|"loads track lyrics"| node_lyrics
node_player -->|"loads track artwork"| node_covers
node_player -->|"starts and controls audio"| node_audio
node_player -->|"persists playback state"| node_settings
node_audio -->|"reads track audio"| node_storage
node_power -->|"mutes audio"| node_audio

click node_v1firmware "https://github.com/ralihachev/musicstation/blob/main/MusicStation.ino"
click node_controls "https://github.com/ralihachev/musicstation/blob/main/V2/MusicStationV2/input.cpp"
click node_ui "https://github.com/ralihachev/musicstation/blob/main/V2/MusicStationV2/ui.cpp"
click node_panel "https://github.com/ralihachev/musicstation/blob/main/V2/MusicStationV2/panel.cpp"
click node_storage "https://github.com/ralihachev/musicstation/blob/main/V2/MusicStationV2/storage.cpp"
click node_library "https://github.com/ralihachev/musicstation/blob/main/V2/MusicStationV2/library.cpp"
click node_metadata "https://github.com/ralihachev/musicstation/blob/main/V2/MusicStationV2/mp3meta.cpp"
click node_playlists "https://github.com/ralihachev/musicstation/blob/main/V2/MusicStationV2/playlist.cpp"
click node_covers "https://github.com/ralihachev/musicstation/blob/main/V2/MusicStationV2/cover.cpp"
click node_lyrics "https://github.com/ralihachev/musicstation/blob/main/V2/MusicStationV2/lyrics.cpp"
click node_player "https://github.com/ralihachev/musicstation/blob/main/V2/MusicStationV2/player.cpp"
click node_audio "https://github.com/ralihachev/musicstation/blob/main/V2/MusicStationV2/audio.cpp"
click node_settings "https://github.com/ralihachev/musicstation/blob/main/V2/MusicStationV2/settings.cpp"
click node_power "https://github.com/ralihachev/musicstation/blob/main/V2/MusicStationV2/power.cpp"

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_v1firmware,node_v1display toneBlue
class node_controls,node_ui,node_panel toneAmber
class node_storage,node_library,node_metadata,node_playlists,node_covers,node_lyrics toneMint
class node_player,node_audio,node_settings toneRose
class node_power,node_phone,node_online toneIndigo
```

## Components

### V1 companion

- [V1 firmware](https://github.com/ralihachev/musicstation/blob/main/MusicStation.ino): `MusicStation.ino`
- **E-paper display**

### V2 interaction

- [Button input](https://github.com/ralihachev/musicstation/blob/main/V2/MusicStationV2/input.cpp): `V2/MusicStationV2/input.cpp`
- [Navigation and UI](https://github.com/ralihachev/musicstation/blob/main/V2/MusicStationV2/ui.cpp): `V2/MusicStationV2/ui.cpp`
- [E-paper panel](https://github.com/ralihachev/musicstation/blob/main/V2/MusicStationV2/panel.cpp): `V2/MusicStationV2/panel.cpp`

### V2 media

- [SD storage](https://github.com/ralihachev/musicstation/blob/main/V2/MusicStationV2/storage.cpp): `V2/MusicStationV2/storage.cpp`
- [Music library index](https://github.com/ralihachev/musicstation/blob/main/V2/MusicStationV2/library.cpp): `V2/MusicStationV2/library.cpp`
- [MP3 metadata](https://github.com/ralihachev/musicstation/blob/main/V2/MusicStationV2/mp3meta.cpp): `V2/MusicStationV2/mp3meta.cpp`
- [Playlist handling](https://github.com/ralihachev/musicstation/blob/main/V2/MusicStationV2/playlist.cpp): `V2/MusicStationV2/playlist.cpp`
- [Local artwork](https://github.com/ralihachev/musicstation/blob/main/V2/MusicStationV2/cover.cpp): `V2/MusicStationV2/cover.cpp`
- [Synchronized lyrics](https://github.com/ralihachev/musicstation/blob/main/V2/MusicStationV2/lyrics.cpp): `V2/MusicStationV2/lyrics.cpp`

### V2 playback

- [Queue and playback](https://github.com/ralihachev/musicstation/blob/main/V2/MusicStationV2/player.cpp): `V2/MusicStationV2/player.cpp`
- [Audio backend](https://github.com/ralihachev/musicstation/blob/main/V2/MusicStationV2/audio.cpp): `V2/MusicStationV2/audio.cpp`
- [Persistent state](https://github.com/ralihachev/musicstation/blob/main/V2/MusicStationV2/settings.cpp): `V2/MusicStationV2/settings.cpp`

### V2 device

- [Power management](https://github.com/ralihachev/musicstation/blob/main/V2/MusicStationV2/power.cpp): `V2/MusicStationV2/power.cpp`

### Other components

- **iPhone**
- **Online services**

## Connections

- iPhone → V1 firmware: sends playback state (evidence: `README.md`)
- Online services → V1 firmware: provides artwork and lyrics (evidence: `README.md`)
- V1 firmware → E-paper display: renders player screen (evidence: `README.md`)
- Button input → Navigation and UI: dispatches input
- Navigation and UI → Queue and playback: controls playback (evidence: `V2/MusicStationV2/ui.cpp`)
- Navigation and UI → Music library index: reads browse records (evidence: `V2/MusicStationV2/ui.cpp`)
- Navigation and UI → Persistent state: updates settings (evidence: `V2/MusicStationV2/ui.cpp`)
- Navigation and UI → Playlist handling: refreshes playlists (evidence: `V2/MusicStationV2/ui.cpp`)
- Navigation and UI → E-paper panel: draws screens
- Music library index → MP3 metadata: probes track metadata (evidence: `V2/MusicStationV2/library.cpp`)
- Music library index → SD storage: reads and writes index
- Playlist handling → SD storage: reads playlist files
- Queue and playback → Music library index: builds track queues (evidence: `V2/MusicStationV2/player.cpp`)
- Queue and playback → Playlist handling: loads playlist queue (evidence: `V2/MusicStationV2/player.cpp`)
- Queue and playback → Synchronized lyrics: loads track lyrics (evidence: `V2/MusicStationV2/player.cpp`)
- Queue and playback → Local artwork: loads track artwork (evidence: `V2/MusicStationV2/player.cpp`)
- Queue and playback → Audio backend: starts and controls audio (evidence: `V2/MusicStationV2/player.cpp`)
- Queue and playback → Persistent state: persists playback state (evidence: `V2/MusicStationV2/player.cpp`)
- Audio backend → SD storage: reads track audio (evidence: `V2/MusicStationV2/audio.cpp`)
- Power management → Audio backend: mutes audio (evidence: `V2/MusicStationV2/power.cpp`)
