# spikerko/spicy-lyrics architecture

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

## Overview

Spicy Lyrics is a Spicetify extension that replaces Spotify’s lyrics view. The principal flow is playback-driven lyric lookup followed by applying and synchronizing lyrics in the view; the product also includes a local TTML library, customizable settings, popup lyrics, and dynamic backgrounds. The app excerpt confirms key orchestration calls, but lyric-provider and rendering internals are not fully sampled, so uncertain connections are omitted.

Main entry points: [`src/app.tsx`](https://github.com/spikerko/spicy-lyrics/blob/main/src/app.tsx) (App bootstrap), [`src/utils/Lyrics/fetchLyrics.ts`](https://github.com/spikerko/spicy-lyrics/blob/main/src/utils/Lyrics/fetchLyrics.ts) (Lyric lookup), [`src/utils/Lyrics/Global/Applyer.ts`](https://github.com/spikerko/spicy-lyrics/blob/main/src/utils/Lyrics/Global/Applyer.ts) (Apply lyrics), [`src/components/ReactComponents/LyricsManager/hooks/useLyricsDB.ts`](https://github.com/spikerko/spicy-lyrics/blob/main/src/components/ReactComponents/LyricsManager/hooks/useLyricsDB.ts) (Library controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Extension runtime"]
  node_app["App bootstrap<br/>[app.tsx]"]
  node_player["Playback state<br/>[SpotifyPlayer.ts]"]
  node_query["API query<br/>[Query.ts]"]
end

subgraph group_lyrics["Lyrics experience"]
  node_lyricsfetch["Lyric lookup<br/>[fetchLyrics.ts]"]
  node_lyricview["Apply lyrics<br/>[Applyer.ts]"]
  node_process["Process lyrics<br/>[ProcessLyrics.ts]"]
  node_animator["Lyrics animation<br/>[Main.ts]"]
end

subgraph group_library["Lyrics library"]
  node_managerui["Lyrics Manager<br/>[index.tsx]"]
  node_dbhook["Library controls<br/>[useLyricsDB.ts]"]
  node_ttml["TTML parser<br/>[parseTTML.ts]"]
  node_localdb[("Local lyric library<br/>[index.ts]")]
end

subgraph group_visuals["Visual experience"]
  node_background["Dynamic backgrounds"]
  node_artistvisuals["Artist visuals<br/>[Main.ts]"]
  node_artistcache[("Artist visual cache<br/>[Cache.ts]")]
  node_popup["Popup lyrics<br/>[PopupLyrics.ts]"]
end

subgraph group_settings["Configuration"]
  node_settingsui["Settings panel<br/>[index.tsx]"]
  node_settings["Settings state<br/>[settings.ts]"]
end

node_spotify(("Spotify desktop"))
node_lyricsapi["Lyrics API"]
node_spotifygraphql["Spotify GraphQL"]

node_spotify -->|"hosts extension"| node_app
node_app -->|"uses playback"| node_player
node_app -->|"fetches lyrics"| node_lyricsfetch
node_lyricsfetch -->|"applies results"| node_lyricview
node_app -->|"applies results"| node_lyricview
node_lyricsfetch -->|"looks up lyrics"| node_lyricsapi
node_query -->|"sends queries"| node_lyricsapi
node_managerui -->|"manages library"| node_dbhook
node_dbhook -->|"reads and writes"| node_localdb
node_dbhook -->|"refetches current track"| node_lyricsfetch
node_ttml -->|"parses imports"| node_localdb
node_settingsui -->|"updates preferences"| node_settings
node_app -->|"initializes backgrounds"| node_background
node_background -->|"requests visuals"| node_artistvisuals
node_artistvisuals -->|"reads and writes"| node_artistcache
node_artistvisuals -->|"requests imagery"| node_spotifygraphql
node_app -->|"opens and closes"| node_popup
node_lyricview -->|"processes lyrics"| node_process
node_lyricview -->|"animates lyrics"| node_animator

click node_app "https://github.com/spikerko/spicy-lyrics/blob/main/src/app.tsx"
click node_player "https://github.com/spikerko/spicy-lyrics/blob/main/src/components/Global/SpotifyPlayer.ts"
click node_lyricsfetch "https://github.com/spikerko/spicy-lyrics/blob/main/src/utils/Lyrics/fetchLyrics.ts"
click node_query "https://github.com/spikerko/spicy-lyrics/blob/main/src/utils/API/Query.ts"
click node_lyricview "https://github.com/spikerko/spicy-lyrics/blob/main/src/utils/Lyrics/Global/Applyer.ts"
click node_process "https://github.com/spikerko/spicy-lyrics/blob/main/src/utils/Lyrics/ProcessLyrics.ts"
click node_animator "https://github.com/spikerko/spicy-lyrics/blob/main/src/utils/Lyrics/Animator/Main.ts"
click node_managerui "https://github.com/spikerko/spicy-lyrics/blob/main/src/components/ReactComponents/LyricsManager/index.tsx"
click node_dbhook "https://github.com/spikerko/spicy-lyrics/blob/main/src/components/ReactComponents/LyricsManager/hooks/useLyricsDB.ts"
click node_ttml "https://github.com/spikerko/spicy-lyrics/blob/main/src/utils/Lyrics/manager/parseTTML.ts"
click node_localdb "https://github.com/spikerko/spicy-lyrics/blob/main/src/utils/Lyrics/manager/index.ts"
click node_settingsui "https://github.com/spikerko/spicy-lyrics/blob/main/src/components/ReactComponents/SettingsPanel/index.tsx"
click node_settings "https://github.com/spikerko/spicy-lyrics/blob/main/src/utils/settings.ts"
click node_background "https://github.com/spikerko/spicy-lyrics/blob/main/src/components/DynamicBG/dynamicBackground.ts"
click node_artistvisuals "https://github.com/spikerko/spicy-lyrics/blob/main/src/components/DynamicBG/ArtistVisuals/HeaderImage/Main.ts"
click node_artistcache "https://github.com/spikerko/spicy-lyrics/blob/main/src/components/DynamicBG/ArtistVisuals/Cache.ts"
click node_popup "https://github.com/spikerko/spicy-lyrics/blob/main/src/components/Utils/PopupLyrics.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_app,node_player,node_query toneBlue
class node_lyricsfetch,node_lyricview,node_process,node_animator toneAmber
class node_managerui,node_dbhook,node_ttml,node_localdb,node_lyricsapi toneMint
class node_background,node_artistvisuals,node_artistcache,node_popup toneRose
class node_settingsui,node_settings,node_spotify,node_spotifygraphql toneIndigo
```

## Components

### Extension runtime

- [App bootstrap](https://github.com/spikerko/spicy-lyrics/blob/main/src/app.tsx): `src/app.tsx`
- [Playback state](https://github.com/spikerko/spicy-lyrics/blob/main/src/components/Global/SpotifyPlayer.ts): `src/components/Global/SpotifyPlayer.ts`
- [API query](https://github.com/spikerko/spicy-lyrics/blob/main/src/utils/API/Query.ts): `src/utils/API/Query.ts`

### Lyrics experience

- [Lyric lookup](https://github.com/spikerko/spicy-lyrics/blob/main/src/utils/Lyrics/fetchLyrics.ts): `src/utils/Lyrics/fetchLyrics.ts`
- [Apply lyrics](https://github.com/spikerko/spicy-lyrics/blob/main/src/utils/Lyrics/Global/Applyer.ts): `src/utils/Lyrics/Global/Applyer.ts`
- [Process lyrics](https://github.com/spikerko/spicy-lyrics/blob/main/src/utils/Lyrics/ProcessLyrics.ts): `src/utils/Lyrics/ProcessLyrics.ts`
- [Lyrics animation](https://github.com/spikerko/spicy-lyrics/blob/main/src/utils/Lyrics/Animator/Main.ts): `src/utils/Lyrics/Animator/Main.ts`

### Lyrics library

- [Lyrics Manager](https://github.com/spikerko/spicy-lyrics/blob/main/src/components/ReactComponents/LyricsManager/index.tsx): `src/components/ReactComponents/LyricsManager/index.tsx`
- [Library controls](https://github.com/spikerko/spicy-lyrics/blob/main/src/components/ReactComponents/LyricsManager/hooks/useLyricsDB.ts): `src/components/ReactComponents/LyricsManager/hooks/useLyricsDB.ts`
- [TTML parser](https://github.com/spikerko/spicy-lyrics/blob/main/src/utils/Lyrics/manager/parseTTML.ts): `src/utils/Lyrics/manager/parseTTML.ts`
- [Local lyric library](https://github.com/spikerko/spicy-lyrics/blob/main/src/utils/Lyrics/manager/index.ts): `src/utils/Lyrics/manager/index.ts`

### Visual experience

- [Dynamic backgrounds](https://github.com/spikerko/spicy-lyrics/blob/main/src/components/DynamicBG/dynamicBackground.ts): `src/components/DynamicBG/dynamicBackground.ts`
- [Artist visuals](https://github.com/spikerko/spicy-lyrics/blob/main/src/components/DynamicBG/ArtistVisuals/HeaderImage/Main.ts): `src/components/DynamicBG/ArtistVisuals/HeaderImage/Main.ts`
- [Artist visual cache](https://github.com/spikerko/spicy-lyrics/blob/main/src/components/DynamicBG/ArtistVisuals/Cache.ts): `src/components/DynamicBG/ArtistVisuals/Cache.ts`
- [Popup lyrics](https://github.com/spikerko/spicy-lyrics/blob/main/src/components/Utils/PopupLyrics.ts): `src/components/Utils/PopupLyrics.ts`

### Configuration

- [Settings panel](https://github.com/spikerko/spicy-lyrics/blob/main/src/components/ReactComponents/SettingsPanel/index.tsx): `src/components/ReactComponents/SettingsPanel/index.tsx`
- [Settings state](https://github.com/spikerko/spicy-lyrics/blob/main/src/utils/settings.ts): `src/utils/settings.ts`

### Other components

- **Spotify desktop**
- **Lyrics API**
- **Spotify GraphQL**

## Connections

- Spotify desktop → App bootstrap: hosts extension
- App bootstrap → Playback state: uses playback
- App bootstrap → Lyric lookup: fetches lyrics
- Lyric lookup → Apply lyrics: applies results
- App bootstrap → Apply lyrics: applies results
- Lyric lookup → Lyrics API: looks up lyrics
- API query → Lyrics API: sends queries
- Lyrics Manager → Library controls: manages library
- Library controls → Local lyric library: reads and writes
- Library controls → Lyric lookup: refetches current track
- TTML parser → Local lyric library: parses imports
- Settings panel → Settings state: updates preferences
- App bootstrap → Dynamic backgrounds: initializes backgrounds
- Dynamic backgrounds → Artist visuals: requests visuals
- Artist visuals → Artist visual cache: reads and writes
- Artist visuals → Spotify GraphQL: requests imagery
- App bootstrap → Popup lyrics: opens and closes
- Apply lyrics → Process lyrics: processes lyrics
- Apply lyrics → Lyrics animation: animates lyrics