# skensmaster/spotui architecture

> Architecture diagram of the GitHub repository skensmaster/spotui, 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/skensmaster/spotui
- Repository: https://github.com/skensmaster/spotui

## Overview

SpoTUI is a keyboard-driven, terminal-style interface layered inside Spotify via Spicetify. Users enter commands or use keybindings, which dispatch playback, search, playlist, lyrics, theme, and appearance actions; panels present interactive results. The runtime also supports onboarding, custom playback visuals, synchronized listening (“Jam”), and a SpoSync companion. The graph follows documented capabilities and indexed module references; unsampled implementation details are represented only where the README or source index supports them.

Main entry points: [`src/commands.js`](https://github.com/skensmaster/spotui/blob/master/src/commands.js) (Command dispatcher), [`src/main.js`](https://github.com/skensmaster/spotui/blob/master/src/main.js) (Runtime bootstrap), [`src/panels.js`](https://github.com/skensmaster/spotui/blob/master/src/panels.js) (Panel navigation), [`src/jam.js`](https://github.com/skensmaster/spotui/blob/master/src/jam.js) (Jam playback sync)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Interface and dispatch"]
  node_main["Runtime bootstrap<br/>[main.js]"]
  node_terminal["Command terminal<br/>[terminal.js]"]
  node_commands["Command dispatcher<br/>[commands.js]"]
  node_panels["Panel navigation<br/>[panels.js]"]
  node_keybinds["Keyboard bindings<br/>[keybinds.js]"]
  node_actions["Listener actions<br/>[actions.js]"]
  node_onboarding["First-run onboarding<br/>[onboarding.js]"]
end

subgraph group_media["Spotify experiences"]
  node_playlists["Playlist browser<br/>[playlists.js]"]
  node_search["Spotify search<br/>[search.js]"]
  node_lyrics["Lyrics panel<br/>[lyrics.js]"]
  node_visualizer["Audio visualizer<br/>[visualizer.js]"]
  node_dj["DJ playback<br/>[dj.js]"]
end

subgraph group_customize["Customization"]
  node_appearance["Appearance controls<br/>[appearance.js]"]
  node_themes["Theme browser<br/>[themes.js]"]
  node_wallpaper["Wallpaper<br/>[wallpaper.js]"]
  node_ascii["ASCII display<br/>[ascii.js]"]
end

subgraph group_runtime["Runtime and integrations"]
  node_jam["Jam playback sync<br/>[jam.js]"]
  node_sync["SpoSync integration<br/>[sync.js]"]
  node_state["Shared runtime state<br/>[state.js]"]
  node_storage[("Preference storage<br/>[storage.js]")]
end

node_user(("Spotify user"))
node_spotify{{"Spotify / Spicetify"}}
node_lrclib{{"LRCLIB lyrics service"}}
node_jamserver{{"Jam relay server"}}
node_sposync["SpoSync companion<br/>[app.py]"]

node_user -->|"enters commands"| node_terminal
node_main -->|"initializes"| node_terminal
node_main -->|"initializes"| node_onboarding
node_main -->|"initializes"| node_appearance
node_main -->|"initializes"| node_jam
node_main -->|"initializes"| node_keybinds
node_terminal -->|"dispatches"| node_commands
node_commands -->|"opens panels"| node_panels
node_commands -->|"loads playlists"| node_playlists
node_commands -->|"dispatches action commands"| node_actions
node_commands -->|"configures bindings"| node_keybinds
node_keybinds -->|"executes commands"| node_commands
node_panels -->|"opens and closes"| node_search
node_panels -->|"renders browser"| node_playlists
node_panels -->|"loads theme feed"| node_themes
node_onboarding -->|"loads theme feed"| node_themes
node_actions -->|"executes listeners"| node_commands
node_search -->|"requests search"| node_spotify
node_lyrics -->|"fetches lyrics"| node_spotify
node_lyrics -->|"fetches lyrics"| node_lrclib
node_playlists -->|"plays selections"| node_spotify
node_appearance -->|"syncs lyrics settings"| node_lyrics
node_jam -->|"sends sync requests"| node_jamserver
node_jam -->|"controls playback"| node_spotify
node_appearance -->|"reads preferences"| node_storage
node_actions -->|"loads and saves actions"| node_storage
node_jam -->|"persists session"| node_storage
node_terminal -->|"renders logo"| node_ascii
node_sync -.->|"companion relationship"| node_sposync

click node_main "https://github.com/skensmaster/spotui/blob/master/src/main.js"
click node_terminal "https://github.com/skensmaster/spotui/blob/master/src/terminal.js"
click node_commands "https://github.com/skensmaster/spotui/blob/master/src/commands.js"
click node_panels "https://github.com/skensmaster/spotui/blob/master/src/panels.js"
click node_keybinds "https://github.com/skensmaster/spotui/blob/master/src/keybinds.js"
click node_actions "https://github.com/skensmaster/spotui/blob/master/src/actions.js"
click node_onboarding "https://github.com/skensmaster/spotui/blob/master/src/onboarding.js"
click node_playlists "https://github.com/skensmaster/spotui/blob/master/src/playlists.js"
click node_search "https://github.com/skensmaster/spotui/blob/master/src/search.js"
click node_lyrics "https://github.com/skensmaster/spotui/blob/master/src/lyrics.js"
click node_visualizer "https://github.com/skensmaster/spotui/blob/master/src/visualizer.js"
click node_dj "https://github.com/skensmaster/spotui/blob/master/src/dj.js"
click node_appearance "https://github.com/skensmaster/spotui/blob/master/src/appearance.js"
click node_themes "https://github.com/skensmaster/spotui/blob/master/src/themes.js"
click node_wallpaper "https://github.com/skensmaster/spotui/blob/master/src/wallpaper.js"
click node_ascii "https://github.com/skensmaster/spotui/blob/master/src/ascii.js"
click node_jam "https://github.com/skensmaster/spotui/blob/master/src/jam.js"
click node_sync "https://github.com/skensmaster/spotui/blob/master/src/sync.js"
click node_state "https://github.com/skensmaster/spotui/blob/master/src/state.js"
click node_storage "https://github.com/skensmaster/spotui/blob/master/src/storage.js"
click node_sposync "https://github.com/skensmaster/spotui/blob/master/sposync/app.py"

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_main,node_terminal,node_commands,node_panels,node_keybinds,node_actions,node_onboarding,node_user toneBlue
class node_playlists,node_search,node_lyrics,node_visualizer,node_dj toneAmber
class node_appearance,node_themes,node_wallpaper,node_ascii,node_jamserver toneMint
class node_jam,node_sync,node_state,node_storage toneRose
class node_spotify,node_lrclib toneIndigo
class node_sposync toneTeal
```

## Components

### Interface and dispatch

- [Runtime bootstrap](https://github.com/skensmaster/spotui/blob/master/src/main.js): `src/main.js`
- [Command terminal](https://github.com/skensmaster/spotui/blob/master/src/terminal.js): `src/terminal.js`
- [Command dispatcher](https://github.com/skensmaster/spotui/blob/master/src/commands.js): `src/commands.js`
- [Panel navigation](https://github.com/skensmaster/spotui/blob/master/src/panels.js): `src/panels.js`
- [Keyboard bindings](https://github.com/skensmaster/spotui/blob/master/src/keybinds.js): `src/keybinds.js`
- [Listener actions](https://github.com/skensmaster/spotui/blob/master/src/actions.js): `src/actions.js`
- [First-run onboarding](https://github.com/skensmaster/spotui/blob/master/src/onboarding.js): `src/onboarding.js`

### Spotify experiences

- [Playlist browser](https://github.com/skensmaster/spotui/blob/master/src/playlists.js): `src/playlists.js`
- [Spotify search](https://github.com/skensmaster/spotui/blob/master/src/search.js): `src/search.js`
- [Lyrics panel](https://github.com/skensmaster/spotui/blob/master/src/lyrics.js): `src/lyrics.js`
- [Audio visualizer](https://github.com/skensmaster/spotui/blob/master/src/visualizer.js): `src/visualizer.js`
- [DJ playback](https://github.com/skensmaster/spotui/blob/master/src/dj.js): `src/dj.js`

### Customization

- [Appearance controls](https://github.com/skensmaster/spotui/blob/master/src/appearance.js): `src/appearance.js`
- [Theme browser](https://github.com/skensmaster/spotui/blob/master/src/themes.js): `src/themes.js`
- [Wallpaper](https://github.com/skensmaster/spotui/blob/master/src/wallpaper.js): `src/wallpaper.js`
- [ASCII display](https://github.com/skensmaster/spotui/blob/master/src/ascii.js): `src/ascii.js`

### Runtime and integrations

- [Jam playback sync](https://github.com/skensmaster/spotui/blob/master/src/jam.js): `src/jam.js`
- [SpoSync integration](https://github.com/skensmaster/spotui/blob/master/src/sync.js): `src/sync.js`
- [Shared runtime state](https://github.com/skensmaster/spotui/blob/master/src/state.js): `src/state.js`
- [Preference storage](https://github.com/skensmaster/spotui/blob/master/src/storage.js): `src/storage.js`

### Other components

- **Spotify user**
- **Spotify / Spicetify**
- **LRCLIB lyrics service**
- **Jam relay server**
- [SpoSync companion](https://github.com/skensmaster/spotui/blob/master/sposync/app.py): `sposync/app.py`

## Connections

- Spotify user → Command terminal: enters commands (evidence: `README.md`)
- Runtime bootstrap → Command terminal: initializes (evidence: `src/main.js`)
- Runtime bootstrap → First-run onboarding: initializes (evidence: `src/main.js`)
- Runtime bootstrap → Appearance controls: initializes (evidence: `src/main.js`)
- Runtime bootstrap → Jam playback sync: initializes (evidence: `src/main.js`)
- Runtime bootstrap → Keyboard bindings: initializes (evidence: `src/main.js`)
- Command terminal → Command dispatcher: dispatches (evidence: `src/terminal.js`)
- Command dispatcher → Panel navigation: opens panels (evidence: `src/commands.js`)
- Command dispatcher → Playlist browser: loads playlists (evidence: `src/commands.js`)
- Command dispatcher → Listener actions: dispatches action commands (evidence: `src/commands.js`)
- Command dispatcher → Keyboard bindings: configures bindings (evidence: `src/commands.js`)
- Keyboard bindings → Command dispatcher: executes commands (evidence: `src/keybinds.js`)
- Panel navigation → Spotify search: opens and closes (evidence: `src/panels.js`)
- Panel navigation → Playlist browser: renders browser (evidence: `src/panels.js`)
- Panel navigation → Theme browser: loads theme feed (evidence: `src/panels.js`)
- First-run onboarding → Theme browser: loads theme feed (evidence: `src/onboarding.js`)
- Listener actions → Command dispatcher: executes listeners (evidence: `src/actions.js`)
- Spotify search → Spotify / Spicetify: requests search (evidence: `src/search.js`)
- Lyrics panel → Spotify / Spicetify: fetches lyrics (evidence: `src/lyrics.js`)
- Lyrics panel → LRCLIB lyrics service: fetches lyrics (evidence: `src/lyrics.js`)
- Playlist browser → Spotify / Spicetify: plays selections (evidence: `src/playlists.js`)
- Appearance controls → Lyrics panel: syncs lyrics settings (evidence: `src/appearance.js`)
- Jam playback sync → Jam relay server: sends sync requests (evidence: `src/jam.js`)
- Jam playback sync → Spotify / Spicetify: controls playback (evidence: `src/jam.js`)
- Appearance controls → Preference storage: reads preferences (evidence: `src/appearance.js`)
- Listener actions → Preference storage: loads and saves actions (evidence: `src/actions.js`)
- Jam playback sync → Preference storage: persists session (evidence: `src/jam.js`)
- Command terminal → ASCII display: renders logo (evidence: `src/terminal.js`)
- SpoSync integration → SpoSync companion: companion relationship
