# bariswha/chorus-for-soundcloud architecture

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

- Interactive diagram: https://gitdiagram.com/bariswha/chorus-for-soundcloud
- Repository: https://github.com/bariswha/chorus-for-soundcloud

## Overview

Chorus is a Chromium extension for shared SoundCloud listening, social features, and personal listening tools. A user opens its panel on SoundCloud; the content script coordinates UI actions, Jam state and playback synchronization, while the page script controls the SoundCloud player through a private message bridge. The service worker owns identity, social and Jam messaging, relays, lyrics requests, and stats operations. README documents additional queue permissions, reactions, presence, chat, sleep timer and localization; unsampled UI and service-worker internals limit the exact links shown for those capabilities.

Main entry points: [`extension/sw.js`](https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/sw.js) (Service worker), [`extension/content.js`](https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/content.js) (Content sync engine), [`extension/ui.js`](https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/ui.js) (Chorus panel), [`extension/bridge.js`](https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/bridge.js) (Page bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["SoundCloud interaction"]
  node_panel["Chorus panel<br/>[ui.js]"]
  node_content["Content sync engine<br/>[content.js]"]
  node_bridge["Page bridge<br/>[bridge.js]"]
  node_player["Player integration<br/>[page.js]"]
end

subgraph group_coordination["Jam coordination"]
  node_worker["Service worker<br/>[sw.js]"]
  node_jam["Jam state and controls<br/>[sw.js]"]
  node_playback["Playback sync<br/>[content.js]"]
  node_queue["Shared queue<br/>[sw.js]"]
end

subgraph group_social["Friends and chat"]
  node_friends["Friends and presence<br/>[sw.js]"]
  node_chat["Encrypted messaging<br/>[sw.js]"]
end

subgraph group_personal["Personal listening"]
  node_stats["Listening stats<br/>[stats.js]"]
  node_recap["Stats and recap UI<br/>[ui.js]"]
  node_lyrics["Lyrics lookup<br/>[lyrics.js]"]
end

subgraph group_foundation["Security and transport"]
  node_clean["Network validation<br/>[clean.js]"]
  node_crypto["Crypto and MQTT<br/>[net.js]"]
  node_language["English and Turkish<br/>[i18n.js]"]
end

node_listener(("Listener"))
node_soundcloud["SoundCloud tab"]
node_relays["MQTT relays"]
node_lrclib["LRCLIB"]

node_listener -->|"opens"| node_panel
node_panel -.->|"sends actions"| node_content
node_content -.->|"sends requests"| node_worker
node_content -->|"uses port"| node_bridge
node_bridge -->|"forwards messages"| node_player
node_player -->|"controls player"| node_soundcloud
node_content -->|"synchronizes"| node_playback
node_worker -->|"dispatches Jam events"| node_jam
node_jam -->|"manages queue"| node_queue
node_worker -->|"manages friends"| node_friends
node_worker -->|"routes messages"| node_chat
node_worker -->|"uses"| node_crypto
node_crypto -->|"publishes encrypted traffic"| node_relays
node_worker -->|"validates network data"| node_clean
node_content -.->|"records listening"| node_stats
node_worker -->|"reads summaries"| node_stats
node_panel -->|"requests summaries"| node_recap
node_worker -->|"requests lyrics"| node_lyrics
node_lyrics -->|"fetches lyrics"| node_lrclib
node_panel -.->|"uses strings"| node_language

click node_panel "https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/ui.js"
click node_content "https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/content.js"
click node_bridge "https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/bridge.js"
click node_player "https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/page.js"
click node_worker "https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/sw.js"
click node_jam "https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/sw.js"
click node_playback "https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/content.js"
click node_queue "https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/sw.js"
click node_friends "https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/sw.js"
click node_chat "https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/sw.js"
click node_stats "https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/stats.js"
click node_recap "https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/ui.js"
click node_lyrics "https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/lyrics.js"
click node_clean "https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/clean.js"
click node_crypto "https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/net.js"
click node_language "https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/i18n.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_panel,node_content,node_bridge,node_player toneBlue
class node_worker,node_jam,node_playback,node_queue toneAmber
class node_friends,node_chat toneMint
class node_stats,node_recap,node_lyrics toneRose
class node_clean,node_crypto,node_language,node_listener,node_soundcloud,node_relays,node_lrclib toneIndigo
```

## Components

### SoundCloud interaction

- [Chorus panel](https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/ui.js): `extension/ui.js`
- [Content sync engine](https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/content.js): `extension/content.js`
- [Page bridge](https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/bridge.js): `extension/bridge.js`
- [Player integration](https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/page.js): `extension/page.js`

### Jam coordination

- [Service worker](https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/sw.js): `extension/sw.js`
- [Jam state and controls](https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/sw.js): `extension/sw.js`
- [Playback sync](https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/content.js): `extension/content.js`
- [Shared queue](https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/sw.js): `extension/sw.js`

### Friends and chat

- [Friends and presence](https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/sw.js): `extension/sw.js`
- [Encrypted messaging](https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/sw.js): `extension/sw.js`

### Personal listening

- [Listening stats](https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/stats.js): `extension/stats.js`
- [Stats and recap UI](https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/ui.js): `extension/ui.js`
- [Lyrics lookup](https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/lyrics.js): `extension/lyrics.js`

### Security and transport

- [Network validation](https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/clean.js): `extension/clean.js`
- [Crypto and MQTT](https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/net.js): `extension/net.js`
- [English and Turkish](https://github.com/bariswha/chorus-for-soundcloud/blob/main/extension/i18n.js): `extension/i18n.js`

### Other components

- **Listener**
- **SoundCloud tab**
- **MQTT relays**
- **LRCLIB**

## Connections

- Listener → Chorus panel: opens (evidence: `README.md`)
- Chorus panel → Content sync engine: sends actions
- Content sync engine → Service worker: sends requests
- Content sync engine → Page bridge: uses port (evidence: `extension/content.js`)
- Page bridge → Player integration: forwards messages (evidence: `extension/bridge.js`)
- Player integration → SoundCloud tab: controls player (evidence: `extension/page.js`)
- Content sync engine → Playback sync: synchronizes (evidence: `extension/content.js`)
- Service worker → Jam state and controls: dispatches Jam events (evidence: `extension/sw.js`)
- Jam state and controls → Shared queue: manages queue (evidence: `extension/sw.js`)
- Service worker → Friends and presence: manages friends (evidence: `README.md`)
- Service worker → Encrypted messaging: routes messages (evidence: `README.md`)
- Service worker → Crypto and MQTT: uses (evidence: `extension/sw.js`)
- Crypto and MQTT → MQTT relays: publishes encrypted traffic (evidence: `README.md`)
- Service worker → Network validation: validates network data (evidence: `extension/sw.js`)
- Content sync engine → Listening stats: records listening
- Service worker → Listening stats: reads summaries (evidence: `extension/sw.js`)
- Chorus panel → Stats and recap UI: requests summaries (evidence: `extension/ui.js`)
- Service worker → Lyrics lookup: requests lyrics (evidence: `extension/sw.js`)
- Lyrics lookup → LRCLIB: fetches lyrics (evidence: `extension/lyrics.js`)
- Chorus panel → English and Turkish: uses strings