# spotx-official/spotx architecture

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

- Interactive diagram: https://gitdiagram.com/spotx-official/spotx
- Repository: https://github.com/spotx-official/spotx

## Overview

SpotX is a Windows Spotify desktop patcher, with companion client-side helpers for filtering home-feed content and reporting listening history. The main user workflow is documented as selecting an installer or PowerShell parameters, then modifying the installed Spotify client; implementation details for that installer and most patch capabilities were not sampled, so those links are documented rather than inferred. The sampled helpers show fetch interception, section filtering, version-reporting logic, and track reporting. The README supplies the broader patch capabilities; unsampled installer internals are represented only at their supported paths.

Main entry points: [`run.ps1`](https://github.com/spotx-official/spotx/blob/main/run.ps1) (PowerShell entry), [`js-helper/checkVersion.js`](https://github.com/spotx-official/spotx/blob/main/js-helper/checkVersion.js) (Version checker), [`js-helper/goofyHistory.js`](https://github.com/spotx-official/spotx/blob/main/js-helper/goofyHistory.js) (Track reporter), [`Install_New_theme.bat`](https://github.com/spotx-official/spotx/blob/main/Install_New_theme.bat) (New-theme install)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_install["Installation and removal"]
  node_new_install["New-theme install"]
  node_old_install["Old-theme install"]
  node_auto_install["Full installer<br/>[Install_Auto.bat]"]
  node_premium_install["Premium installer<br/>[Install_Prem.bat]"]
  node_powershell_entry["PowerShell entry<br/>[run.ps1]"]
  node_uninstall["Uninstaller<br/>[Uninstall.bat]"]
end

subgraph group_patch["Client modifications"]
  node_client_patches["Client patches"]
  node_patch_config["Patch catalog<br/>[patches.json]"]
  node_lyrics_colors["Lyrics colors<br/>[colors.css]"]
  node_lyrics_rules["Lyrics rules<br/>[rules.css]"]
end

subgraph group_helpers["Client helpers"]
  node_section_filter["Home-feed filter<br/>[sectionBlock.js]"]
  node_history_reporter["Track reporter<br/>[goofyHistory.js]"]
end

subgraph group_report["Version reporting"]
  node_version_checker["Version checker<br/>[checkVersion.js]"]
end

node_user(("Windows user"))
node_spotify["Spotify desktop"]
node_update_service["Spotify update API"]
node_ingest_service["Version ingest service"]
node_google_form["Google Form"]
node_local_storage[("Browser local storage")]

node_user -->|"runs"| node_new_install
node_user -->|"runs"| node_old_install
node_user -->|"runs"| node_auto_install
node_user -->|"runs"| node_premium_install
node_user -->|"invokes"| node_powershell_entry
node_user -->|"runs"| node_uninstall
node_new_install -.->|"invokes"| node_powershell_entry
node_old_install -.->|"invokes"| node_powershell_entry
node_auto_install -.->|"invokes"| node_powershell_entry
node_premium_install -.->|"invokes"| node_powershell_entry
node_powershell_entry -->|"patches"| node_spotify
node_uninstall -.->|"removes modifications"| node_spotify
node_client_patches -->|"modifies"| node_spotify
node_patch_config -.->|"defines patches"| node_client_patches
node_lyrics_colors -.->|"styles lyrics"| node_spotify
node_lyrics_rules -.->|"styles lyrics"| node_spotify
node_spotify -->|"fetches feed"| node_section_filter
node_section_filter -->|"returns filtered feed"| node_spotify
node_spotify -.->|"emits track event"| node_history_reporter
node_history_reporter -->|"reads and writes"| node_local_storage
node_history_reporter -->|"posts track URI"| node_google_form
node_spotify -.->|"provides update context"| node_version_checker
node_version_checker -->|"requests update assets"| node_update_service
node_version_checker -->|"reports results"| node_ingest_service
node_version_checker -.->|"stores success report"| node_local_storage

click node_new_install "https://github.com/spotx-official/spotx/blob/main/Install_New_theme.bat"
click node_old_install "https://github.com/spotx-official/spotx/blob/main/Install_Old_theme.bat"
click node_auto_install "https://github.com/spotx-official/spotx/blob/main/scripts/Install_Auto.bat"
click node_premium_install "https://github.com/spotx-official/spotx/blob/main/scripts/Install_Prem.bat"
click node_powershell_entry "https://github.com/spotx-official/spotx/blob/main/run.ps1"
click node_uninstall "https://github.com/spotx-official/spotx/blob/main/Uninstall.bat"
click node_client_patches "https://github.com/spotx-official/spotx/tree/main/patches"
click node_patch_config "https://github.com/spotx-official/spotx/blob/main/patches/patches.json"
click node_lyrics_colors "https://github.com/spotx-official/spotx/blob/main/css-helper/lyrics-color/colors.css"
click node_lyrics_rules "https://github.com/spotx-official/spotx/blob/main/css-helper/lyrics-color/rules.css"
click node_section_filter "https://github.com/spotx-official/spotx/blob/main/js-helper/sectionBlock.js"
click node_history_reporter "https://github.com/spotx-official/spotx/blob/main/js-helper/goofyHistory.js"
click node_version_checker "https://github.com/spotx-official/spotx/blob/main/js-helper/checkVersion.js"

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_new_install,node_old_install,node_auto_install,node_premium_install,node_powershell_entry,node_uninstall,node_user toneBlue
class node_client_patches,node_patch_config,node_lyrics_colors,node_lyrics_rules,node_local_storage toneAmber
class node_section_filter,node_history_reporter,node_update_service toneMint
class node_version_checker toneRose
class node_spotify,node_ingest_service,node_google_form toneIndigo
```

## Components

### Installation and removal

- [New-theme install](https://github.com/spotx-official/spotx/blob/main/Install_New_theme.bat): `Install_New_theme.bat`
- [Old-theme install](https://github.com/spotx-official/spotx/blob/main/Install_Old_theme.bat): `Install_Old_theme.bat`
- [Full installer](https://github.com/spotx-official/spotx/blob/main/scripts/Install_Auto.bat): `scripts/Install_Auto.bat`
- [Premium installer](https://github.com/spotx-official/spotx/blob/main/scripts/Install_Prem.bat): `scripts/Install_Prem.bat`
- [PowerShell entry](https://github.com/spotx-official/spotx/blob/main/run.ps1): `run.ps1`
- [Uninstaller](https://github.com/spotx-official/spotx/blob/main/Uninstall.bat): `Uninstall.bat`

### Client modifications

- [Client patches](https://github.com/spotx-official/spotx/tree/main/patches): `patches`
- [Patch catalog](https://github.com/spotx-official/spotx/blob/main/patches/patches.json): `patches/patches.json`
- [Lyrics colors](https://github.com/spotx-official/spotx/blob/main/css-helper/lyrics-color/colors.css): `css-helper/lyrics-color/colors.css`
- [Lyrics rules](https://github.com/spotx-official/spotx/blob/main/css-helper/lyrics-color/rules.css): `css-helper/lyrics-color/rules.css`

### Client helpers

- [Home-feed filter](https://github.com/spotx-official/spotx/blob/main/js-helper/sectionBlock.js): `js-helper/sectionBlock.js`
- [Track reporter](https://github.com/spotx-official/spotx/blob/main/js-helper/goofyHistory.js): `js-helper/goofyHistory.js`

### Version reporting

- [Version checker](https://github.com/spotx-official/spotx/blob/main/js-helper/checkVersion.js): `js-helper/checkVersion.js`

### Other components

- **Windows user**
- **Spotify desktop**
- **Spotify update API**
- **Version ingest service**
- **Google Form**
- **Browser local storage**

## Connections

- Windows user → New-theme install: runs (evidence: `README.md`)
- Windows user → Old-theme install: runs (evidence: `README.md`)
- Windows user → Full installer: runs (evidence: `README.md`)
- Windows user → Premium installer: runs (evidence: `README.md`)
- Windows user → PowerShell entry: invokes (evidence: `README.md`)
- Windows user → Uninstaller: runs (evidence: `README.md`)
- New-theme install → PowerShell entry: invokes
- Old-theme install → PowerShell entry: invokes
- Full installer → PowerShell entry: invokes
- Premium installer → PowerShell entry: invokes
- PowerShell entry → Spotify desktop: patches (evidence: `README.md`)
- Uninstaller → Spotify desktop: removes modifications
- Client patches → Spotify desktop: modifies (evidence: `README.md`)
- Patch catalog → Client patches: defines patches
- Lyrics colors → Spotify desktop: styles lyrics
- Lyrics rules → Spotify desktop: styles lyrics
- Spotify desktop → Home-feed filter: fetches feed (evidence: `js-helper/sectionBlock.js`)
- Home-feed filter → Spotify desktop: returns filtered feed (evidence: `js-helper/sectionBlock.js`)
- Spotify desktop → Track reporter: emits track event
- Track reporter → Browser local storage: reads and writes (evidence: `js-helper/goofyHistory.js`)
- Track reporter → Google Form: posts track URI (evidence: `js-helper/goofyHistory.js`)
- Spotify desktop → Version checker: provides update context
- Version checker → Spotify update API: requests update assets (evidence: `js-helper/checkVersion.js`)
- Version checker → Version ingest service: reports results (evidence: `js-helper/checkVersion.js`)
- Version checker → Browser local storage: stores success report
