# revir/spotify-on-browser architecture

> Architecture diagram of the GitHub repository revir/spotify-on-browser, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/revir/spotify-on-browser
- Repository: https://github.com/revir/spotify-on-browser

## Overview

##### Project type and purpose
- This is a browser‐extension project (Chrome, Firefox, Edge) whose goal is to present a “Spotify Connect”–style player inside the browser.
- It implements a custom Spotify Connect endpoint so users can send playback from their phone/desktop Spotify client to the browser, control it with global shortcuts, and keep it running in the background without an open tab.

##### File structure
Top‐level files and folders:
- manifest.json (extension entrypoint)
- src/
– authorized.html (OAuth redirect page)
– offscreen.html (headless UI for background audio)
– player.html (main popup/UI)
– option.html + src/option/* (settings page)
– background/ (service worker–style scripts)
– content/ (injected scripts for Spotify web player)
– fonts/, images/, vendor/
– utils.coffee (shared utilities)
- utils/
– build.js, env.js, webserver.js (dev server & build helpers)
– autoReloadClients/ (hot‐reload for dev background & content scripts)
- webpack.config.js (bundling)
- pack.sh (packaging script)

Architectural patterns implied:
– Chrome Extension “Manifest v2/v3” model with distinct entry points
– Publisher–subscriber messaging between background and content scripts
– OAuth redirect flow (authorized.html)
– Offscreen document for continuous audio playback

##### README for additional insights
- Describes user flow: OAuth → inject into Spotify tab → transfer playback → background player
- Mentions using Spotify Web API and Spotify Connect protocols
- Build instructions reference webpack/dev‐server and build output to build/

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Actors and external services
    User["User"]:::external
    spotifyAPI["Spotify Web API"]:::external
    storage["Chrome Storage API"]:::external

    %% Extension Boundary
    subgraph "Browser Extension"
        manifest["manifest.json"]:::core

        subgraph "Background Service Worker"
            mainJS["main.js"]:::core
            messageCoffee["message.coffee"]:::core
            offplayerJS["offplayer.js"]:::core
        end

        subgraph "Content Scripts"
            authorizedCS["authorized.coffee"]:::core
            playerCS["player.coffee"]:::core
        end

        subgraph "UI Pages"
            popup["player.html"]:::ui
            popupLess["player.less"]:::ui
            options["option.html"]:::ui
            optionJS["option.coffee"]:::ui
            oauthPage["authorized.html"]:::ui
        end

        offscreen["offscreen.html"]:::ui

        subgraph "Shared Utilities"
            utilsShared["utils.coffee"]:::core
        end
    end

    %% Dev & Build Tools
    subgraph "Dev & Build Tools"
        webpack["webpack.config.js"]:::dev
        pack["pack.sh"]:::dev
        buildJS["build.js"]:::dev
        envJS["env.js"]:::dev
        webserver["webserver.js"]:::dev
        hotBg["backgroundClient.js"]:::dev
        hotContent["contentScriptClient.js"]:::dev
    end

    %% Interactions
    User -->|"clicks icon"| popup
    popup -->|"sendMessage"| mainJS
    options -->|"sendMessage"| mainJS
    oauthPage -->|"deliver token"| mainJS
    mainJS -->|"store token"| storage
    mainJS -->|"chrome.tabs.sendMessage"| authorizedCS
    mainJS -->|"chrome.tabs.sendMessage"| playerCS
    authorizedCS -->|"interact with Spotify DOM"| spotifyAPI
    playerCS -->|"intercept controls"| spotifyAPI
    mainJS -->|"HTTP requests"| spotifyAPI
    mainJS -->|"open audio context"| offscreen
    mainJS -->|"use utilities"| utilsShared

    %% Build tools connections
    webpack --> pack
    webpack --> buildJS
    buildJS --> envJS
    buildJS --> webserver
    hotBg --> buildJS
    hotContent --> buildJS

    %% Entrypoint mapping
    manifest --> mainJS
    manifest --> authorizedCS
    manifest --> playerCS
    manifest --> popup
    manifest --> options
    manifest --> oauthPage
    manifest --> offscreen

    %% Click Events
    click manifest "https://github.com/revir/spotify-on-browser/blob/main/src/manifest.json"
    click mainJS "https://github.com/revir/spotify-on-browser/blob/main/src/background/main.js"
    click messageCoffee "https://github.com/revir/spotify-on-browser/blob/main/src/background/message.coffee"
    click offplayerJS "https://github.com/revir/spotify-on-browser/blob/main/src/background/offplayer.js"
    click authorizedCS "https://github.com/revir/spotify-on-browser/blob/main/src/content/authorized.coffee"
    click playerCS "https://github.com/revir/spotify-on-browser/blob/main/src/content/player.coffee"
    click popup "https://github.com/revir/spotify-on-browser/blob/main/src/player.html"
    click popupLess "https://github.com/revir/spotify-on-browser/blob/main/src/content/player.less"
    click options "https://github.com/revir/spotify-on-browser/blob/main/src/option.html"
    click optionJS "https://github.com/revir/spotify-on-browser/blob/main/src/option/option.coffee"
    click oauthPage "https://github.com/revir/spotify-on-browser/blob/main/src/authorized.html"
    click offscreen "https://github.com/revir/spotify-on-browser/blob/main/src/offscreen.html"
    click utilsShared "https://github.com/revir/spotify-on-browser/blob/main/src/utils.coffee"
    click webpack "https://github.com/revir/spotify-on-browser/blob/main/webpack.config.js"
    click pack "https://github.com/revir/spotify-on-browser/blob/main/pack.sh"
    click buildJS "https://github.com/revir/spotify-on-browser/blob/main/utils/build.js"
    click envJS "https://github.com/revir/spotify-on-browser/blob/main/utils/env.js"
    click webserver "https://github.com/revir/spotify-on-browser/blob/main/utils/webserver.js"
    click hotBg "https://github.com/revir/spotify-on-browser/blob/main/utils/autoReloadClients/backgroundClient.js"
    click hotContent "https://github.com/revir/spotify-on-browser/blob/main/utils/autoReloadClients/contentScriptClient.js"

    %% Styles
    classDef core fill:#D0E6FF,stroke:#0366d6
    classDef ui fill:#DFFFE0,stroke:#28a745
    classDef external fill:#FFE6CC,stroke:#d73a49
    classDef dev fill:#EEEEEE,stroke:#666666
```
