# spotx-official/spotx-bash architecture

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

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

## Overview

1. **Repository shape**
   - This is a very small, single-purpose Bash-based distribution repo.
   - The only executable product is `spotx.sh`; the rest is documentation and GitHub issue scaffolding.
   - There is no backend, no compiled service, and no persistent application state in the repo itself.

2. **Primary purpose**
   - The script customizes the local Spotify desktop client on **Linux and macOS**.
   - Its core job is to patch or configure the installed client so ads, logging, and certain UI features are disabled or hidden.
   - It also supports related lifecycle actions like installing supported client versions, rolling back, uninstalling, and clearing cache.

3. **Main entrypoint / execution model**
   - The repo is designed to be run directly from the terminal via `bash <(curl ...)`.
   - That means the effective runtime boundary is: **remote script delivery → local shell execution**.
   - The script is meant to be invoked interactively or non-interactively through command-line flags.

4. **Input surface: CLI options**
   - The architecture is driven by command-line flags rather than a GUI or config file.
   - Options control major behavior groups:
     - patching mode (`-p` premium, default free-tier behavior)
     - feature toggles (`-d`, `-e`, `-h`, `-o`, `-l`)
     - operational behavior (`-i`, `-f`, `-c`, `-P`)
     - platform-specific install/update behavior (`--installdeb`, `--installmac`, `--rollback`, `-B`, `-S`)
   - This makes the script a command-driven orchestrator over local client files and system tools.

5. **Target systems and platform split**
   - The repo explicitly supports **Linux** and **macOS**.
   - Some behaviors are platform-specific:
     - Linux: install latest Spotify desktop package on APT-based distros, optionally stable/testing branch.
     - macOS: install latest supported client, rollback support, and optional auto-update blocking.
   - A diagram should show a shared patching flow with platform branches for install and update handling.

6. **Core functional boundary: Spotify client patching**
   - The central boundary is the **installed Spotify desktop application**.
   - The script likely modifies app resources, config, or bundled assets to:
     - block audio/banner/video ads
     - block logging
     - enable developer/experimental features
     - hide podcasts/audiobooks/episodes from the home screen
     - optionally set lyrics/background/UI preferences
   - In architecture terms, the local Spotify app is the primary system-under-modification, not a service the repo hosts.

7. **Installation and update management**
   - The repo also acts as a lightweight installer/updater for Spotify desktop client packages.
   - On Linux, it can fetch and install a supported `.deb` package.
   - On macOS, it can install the latest supported client, or roll back to a previous supported version.
   - This is a separate subsystem from patching, but both feed into the same end state: a usable, modified local client.

8. **Environment detection and path resolution**
   - The `-P <path>` option shows that the script supports explicit client location overrides.
   - That implies the script must discover or accept the Spotify installation path before it can modify files.
   - A good diagram should include a step for locating the client on disk, because it is a prerequisite for all patching actions.

9. **Operational safeguards and packaging behavior**
   - The script includes options for:
     - clearing app cache
     - forcing execution
     - disabling colorized output
     - skipping codesigning on macOS
     - uninstalling SpotX-Bash changes
   - These indicate the script is meant to be safe enough for repeat runs and reversible enough to clean up after itself.
   - On macOS, codesigning is a meaningful boundary because modifying app bundles can affect launchability and OS trust.

10. **External dependencies and trust boundaries**
   - The repo relies on external sources for delivery and execution:
     - `spotx-official.github.io` for hosted run scripts and assets
     - GitHub raw URLs for direct script retrieval
     - Spotify’s own desktop client packages/binaries
   - The trust boundary is important: the repo does not serve an API; it fetches and patches third-party software locally.

11. **GitHub repo support surface**
   - `.github/ISSUE_TEMPLATE/bug_report.yml` and the image assets are support metadata, not runtime components.
   - Their role is operational: collecting bug reports and maintaining project presentation.
   - They do not affect the patching architecture, but they indicate the repo is maintained as a user-facing tooling project.

12. **Best architecture diagram framing**
   - Model this repo as a **single Bash orchestrator** that:
     1. accepts CLI input,
     2. detects OS and options,
     3. locates or installs the Spotify client,
     4. patches local client files/settings,
     5. optionally performs macOS-specific signing/update controls,
     6. exits with the modified local app.
   - The key components are not services but **script logic, local filesystem targets, and external package/script sources**.

Main entry points: [`spotx.sh`](https://github.com/spotx-official/spotx-bash/blob/main/spotx.sh) (CLI flags), [`README.md`](https://github.com/spotx-official/spotx-bash/blob/main/README.md) (README), [`.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/spotx-official/spotx-bash/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml) (Bug report)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_runtime["Runtime & entry"]
  node_n_remote_run(("Remote run<br/>delivery path"))
  node_n_sources["External sources<br/>third-party inputs"]
end

subgraph group_grp_core["SpotX script"]
  node_n_cli["CLI flags<br/>option parser<br/>[spotx.sh]"]
  node_n_detect["OS detect<br/>platform gate<br/>[spotx.sh]"]
  node_n_locate["Find client<br/>path resolver<br/>[spotx.sh]"]
  node_n_patch["Patch engine<br/>client modifier<br/>[spotx.sh]"]
  node_n_features["Feature toggles<br/>patch options<br/>[spotx.sh]"]
  node_n_ops["Ops controls<br/>lifecycle actions<br/>[spotx.sh]"]
  node_n_linux["Linux path<br/>platform flow<br/>[spotx.sh]"]
  node_n_linux_install["Install deb<br/>package installer<br/>[spotx.sh]"]
  node_n_linux_branch["Stable/test<br/>release selector<br/>[spotx.sh]"]
  node_n_macos["macOS path<br/>platform flow<br/>[spotx.sh]"]
  node_n_macos_install["Install app<br/>app installer<br/>[spotx.sh]"]
  node_n_macos_rollback["Rollback<br/>version manager<br/>[spotx.sh]"]
  node_n_codesign["Codesign<br/>mac trust step<br/>[spotx.sh]"]
end

subgraph group_grp_targets["Local client targets"]
  node_n_spotify[("Spotify app<br/>local target")]
end

subgraph group_grp_support["Repo support"]
  node_n_readme["README<br/>documentation<br/>[README.md]"]
  node_n_issues["Bug report<br/>support template<br/>[bug_report.yml]"]
end

node_n_sources -->|"delivers"| node_n_remote_run
node_n_remote_run -->|"invokes"| node_n_cli
node_n_cli -->|"routes"| node_n_detect
node_n_detect -->|"selects"| node_n_locate
node_n_locate -->|"targets"| node_n_spotify
node_n_cli -->|"controls"| node_n_features
node_n_cli -->|"controls"| node_n_ops
node_n_cli -->|"starts"| node_n_patch
node_n_patch -->|"modifies"| node_n_spotify
node_n_patch -.->|"on macOS"| node_n_codesign
node_n_detect -->|"branches"| node_n_linux
node_n_detect -->|"branches"| node_n_macos
node_n_linux -->|"selects"| node_n_linux_branch
node_n_linux_branch -->|"feeds"| node_n_linux_install
node_n_linux_install -->|"installs"| node_n_spotify
node_n_macos -->|"installs"| node_n_macos_install
node_n_macos -->|"reverts"| node_n_macos_rollback
node_n_macos_install -->|"places"| node_n_spotify
node_n_macos_rollback -->|"restores"| node_n_spotify
node_n_readme -.->|"documents"| node_n_cli
node_n_issues -.->|"supports"| node_n_patch

click node_n_cli "https://github.com/spotx-official/spotx-bash/blob/main/spotx.sh"
click node_n_detect "https://github.com/spotx-official/spotx-bash/blob/main/spotx.sh"
click node_n_locate "https://github.com/spotx-official/spotx-bash/blob/main/spotx.sh"
click node_n_patch "https://github.com/spotx-official/spotx-bash/blob/main/spotx.sh"
click node_n_features "https://github.com/spotx-official/spotx-bash/blob/main/spotx.sh"
click node_n_ops "https://github.com/spotx-official/spotx-bash/blob/main/spotx.sh"
click node_n_linux "https://github.com/spotx-official/spotx-bash/blob/main/spotx.sh"
click node_n_linux_install "https://github.com/spotx-official/spotx-bash/blob/main/spotx.sh"
click node_n_linux_branch "https://github.com/spotx-official/spotx-bash/blob/main/spotx.sh"
click node_n_macos "https://github.com/spotx-official/spotx-bash/blob/main/spotx.sh"
click node_n_macos_install "https://github.com/spotx-official/spotx-bash/blob/main/spotx.sh"
click node_n_macos_rollback "https://github.com/spotx-official/spotx-bash/blob/main/spotx.sh"
click node_n_codesign "https://github.com/spotx-official/spotx-bash/blob/main/spotx.sh"
click node_n_readme "https://github.com/spotx-official/spotx-bash/blob/main/README.md"
click node_n_issues "https://github.com/spotx-official/spotx-bash/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml"

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_n_remote_run,node_n_sources toneBlue
class node_n_cli,node_n_detect,node_n_locate,node_n_patch,node_n_features,node_n_ops,node_n_linux,node_n_linux_install,node_n_linux_branch,node_n_macos,node_n_macos_install,node_n_macos_rollback,node_n_codesign toneAmber
class node_n_spotify toneMint
class node_n_readme,node_n_issues toneRose
```

## Components

### Runtime & entry

Remote delivery and local shell execution boundary.

- **Remote run**: delivery path · bash <(curl ...) style execution from hosted script content.
- **External sources**: third-party inputs · Hosted scripts, raw GitHub assets, and Spotify packages used during delivery and install.

### SpotX script

Main Bash orchestration inside spotx.sh.

- [CLI flags](https://github.com/spotx-official/spotx-bash/blob/main/spotx.sh): option parser · Command-line switches that control patching, install, rollback, cleanup, and platform behavior. · `spotx.sh`
- [OS detect](https://github.com/spotx-official/spotx-bash/blob/main/spotx.sh): platform gate · Branches execution for Linux and macOS specific behavior. · `spotx.sh`
- [Find client](https://github.com/spotx-official/spotx-bash/blob/main/spotx.sh): path resolver · Discovers or accepts the Spotify installation path before modification. · `spotx.sh`
- [Patch engine](https://github.com/spotx-official/spotx-bash/blob/main/spotx.sh): client modifier · Applies local Spotify changes to disable ads, logging, and selected UI features. · `spotx.sh`
- [Feature toggles](https://github.com/spotx-official/spotx-bash/blob/main/spotx.sh): patch options · Controls premium/free mode and UI or content visibility tweaks. · `spotx.sh`
- [Ops controls](https://github.com/spotx-official/spotx-bash/blob/main/spotx.sh): lifecycle actions · Force run, clear cache, uninstall, color handling, and other operational flags. · `spotx.sh`
- [Linux path](https://github.com/spotx-official/spotx-bash/blob/main/spotx.sh): platform flow · Linux-specific install and patch flow for apt-based Spotify desktop packages. · `spotx.sh`
- [Install deb](https://github.com/spotx-official/spotx-bash/blob/main/spotx.sh): package installer · Fetches and installs a supported Spotify .deb package on Linux. · `spotx.sh`
- [Stable/test](https://github.com/spotx-official/spotx-bash/blob/main/spotx.sh): release selector · Chooses the Linux package branch or build source. · `spotx.sh`
- [macOS path](https://github.com/spotx-official/spotx-bash/blob/main/spotx.sh): platform flow · macOS-specific install, patch, rollback, and signing flow. · `spotx.sh`
- [Install app](https://github.com/spotx-official/spotx-bash/blob/main/spotx.sh): app installer · Installs the latest supported Spotify client on macOS. · `spotx.sh`
- [Rollback](https://github.com/spotx-official/spotx-bash/blob/main/spotx.sh): version manager · Reverts to a previous supported Spotify client version on macOS. · `spotx.sh`
- [Codesign](https://github.com/spotx-official/spotx-bash/blob/main/spotx.sh): mac trust step · Re-signs modified app bundles when needed for macOS launchability. · `spotx.sh`

### Local client targets

Installed Spotify app and filesystem locations the script modifies.

- **Spotify app**: local target · Installed Spotify desktop client on the user's machine.

### Repo support

Documentation and issue reporting assets.

- [README](https://github.com/spotx-official/spotx-bash/blob/main/README.md): documentation · Primary usage and project overview documentation. · `README.md`
- [Bug report](https://github.com/spotx-official/spotx-bash/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml): support template · GitHub issue template for collecting bug reports. · `.github/ISSUE_TEMPLATE/bug_report.yml`

## Connections

- External sources → Remote run: delivers · Hosted assets provide the script and install sources.
- Remote run → CLI flags: invokes · Remote shell execution enters the Bash orchestrator.
- CLI flags → OS detect: routes · Flags are interpreted after initial option parsing.
- OS detect → Find client: selects · Platform detection determines how the client path is resolved.
- Find client → Spotify app: targets · Resolved installation path points at the local Spotify app.
- CLI flags → Feature toggles: controls · Feature-related flags adjust patch behavior.
- CLI flags → Ops controls: controls · Operational flags change run mode and cleanup behavior.
- CLI flags → Patch engine: starts · CLI execution eventually drives the patching workflow.
- Patch engine → Spotify app: modifies · Local app files and settings are patched in place.
- Patch engine → Codesign: on macOS · Modified app bundles may need re-signing.
- OS detect → Linux path: branches · Linux-specific flow for package installation and patching.
- OS detect → macOS path: branches · macOS-specific flow for install, rollback, and signing.
- Linux path → Stable/test: selects · Chooses stable or testing package channel.
- Stable/test → Install deb: feeds · Release selection informs the package install step.
- Install deb → Spotify app: installs · A supported Spotify package is installed locally.
- macOS path → Install app: installs · macOS flow can install the supported client.
- macOS path → Rollback: reverts · macOS flow can roll back to a previous supported version.
- Install app → Spotify app: places · The installed app becomes the patch target.
- Rollback → Spotify app: restores · Rolled-back app version becomes the patch target.
- README → CLI flags: documents · README explains script usage and options.
- Bug report → Patch engine: supports · Bug reports track problems in the patching workflow.