# whimsypingu/scuttle architecture

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

- Interactive diagram: https://gitdiagram.com/whimsypingu/scuttle
- Repository: https://github.com/whimsypingu/scuttle
- Video tour (about a minute): https://gitdiagram.com/whimsypingu/scuttle/video

## Overview

Scuttle is a self-hosted audio archive: users search their library or discover audio, queue downloads, then play and organize tracks through a browser. The graph follows documented backend REST/WebSocket and frontend responsibilities, with database, workers, playlist import, metadata enrichment, and audio processing represented as distinct stages. Source excerpts support selected calls; README statements support the client/server and remote-access links. Several router and integration implementations were not sampled, so uncertain internal wiring is omitted.

Main entry points: [`backend/server.py`](https://github.com/whimsypingu/scuttle/blob/main/backend/server.py) (FastAPI server), [`backend/core/database/audio_database.py`](https://github.com/whimsypingu/scuttle/blob/main/backend/core/database/audio_database.py) (Audio library), [`backend/api/routers/search_router.py`](https://github.com/whimsypingu/scuttle/blob/main/backend/api/routers/search_router.py) (Search API), [`backend/core/worker/download.py`](https://github.com/whimsypingu/scuttle/blob/main/backend/core/worker/download.py) (Download worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend services"]
  node_server["FastAPI server<br/>[server.py]"]
  node_search_api["Search API<br/>[search_router.py]"]
  node_playlist_api["Playlist API"]
  node_queue_api["Queue API<br/>[queue_router.py]"]
  node_audio_api["Audio API<br/>[audio_router.py]"]
  node_ws_api["WebSocket API"]
  node_database[("Audio library<br/>[audio_database.py]")]
  node_youtube["Audio discovery<br/>[client.py]"]
  node_download_worker["Download worker<br/>[download.py]"]
  node_download_queue["Download queue<br/>[download_queue.py]"]
  node_processor["Audio processing<br/>[processor.py]"]
  node_play_queue["Playback queue<br/>[play_queue.py]"]
  node_stream["Audio streaming<br/>[stream.py]"]
  node_playlist_manager["Playlist manager<br/>[manager.py]"]
  node_spotify_import["Spotify import"]
  node_enrich_worker["Metadata enrichment<br/>[enrich.py]"]
  node_musicbrainz["MusicBrainz client<br/>[client.py]"]
  node_event_bus["Event bus<br/>[event_bus.py]"]
  node_event_handlers["Event handlers<br/>[handlers.py]"]
  node_ws_manager["WebSocket manager<br/>[manager.py]"]
end

subgraph group_frontend["Browser client"]
  node_frontend_main["Client bootstrap<br/>[main.js]"]
  node_search_ui["Search interface<br/>[controller.js]"]
  node_audio_ui["Playback controls<br/>[controller.js]"]
  node_queue_ui["Queue interface<br/>[controller.js]"]
  node_playlist_ui["Playlist interface<br/>[controller.js]"]
  node_popup_ui["Playlist dialogs<br/>[controller.js]"]
  node_client_stores["Client state<br/>[TrackStore.js]"]
  node_ws_client["Live updates<br/>[handlers.js]"]
end

subgraph group_launcher["Desktop launcher"]
  node_launcher_app["Desktop controls<br/>[app.rs]"]
end

node_user(("Listener"))
node_browser(("Web browser"))
node_cloudflared["Cloudflared tunnel"]
node_discord["Discord webhook"]

node_user -->|"uses"| node_browser
node_browser -->|"REST requests"| node_server
node_server -->|"WebSocket events"| node_browser
node_server -.->|"routes to"| node_search_api
node_search_api -->|"searches"| node_database
node_search_api -->|"deep searches"| node_youtube
node_search_api -.->|"enqueues job"| node_download_queue
node_server -.->|"routes to"| node_playlist_api
node_playlist_api -.->|"reads library"| node_database
node_playlist_api -->|"uses"| node_playlist_manager
node_server -.->|"routes to"| node_queue_api
node_server -.->|"routes to"| node_audio_api
node_server -.->|"routes to"| node_ws_api
node_server -->|"initializes"| node_database
node_server -->|"starts"| node_download_worker
node_server -->|"configures"| node_download_queue
node_server -->|"configures"| node_play_queue
node_server -->|"starts"| node_enrich_worker
node_server -->|"configures"| node_processor
node_server -->|"configures"| node_youtube
node_server -->|"configures"| node_musicbrainz
node_server -->|"configures"| node_event_bus
node_server -->|"registers"| node_event_handlers
node_server -->|"configures"| node_ws_manager
node_download_worker -.->|"downloads"| node_youtube
node_download_worker -.->|"processes audio"| node_processor
node_download_worker -.->|"registers tracks"| node_database
node_enrich_worker -.->|"enriches from"| node_musicbrainz
node_enrich_worker -.->|"updates metadata"| node_database
node_playlist_manager -->|"delegates to"| node_spotify_import
node_database -->|"publishes events"| node_event_bus
node_event_handlers -->|"subscribes"| node_event_bus
node_event_handlers -->|"broadcasts"| node_ws_manager
node_frontend_main -.->|"initializes"| node_search_ui
node_search_ui -.->|"searches and queues"| node_server
node_audio_ui -->|"controls playback"| node_queue_ui
node_playlist_ui -->|"loads tracks"| node_audio_ui
node_playlist_ui -->|"adds tracks"| node_queue_ui
node_playlist_ui -.->|"updates state"| node_client_stores
node_popup_ui -->|"renders playlists"| node_playlist_ui
node_popup_ui -.->|"deletes playlists"| node_server
node_ws_client -->|"updates state"| node_client_stores
node_ws_client -->|"refreshes interface"| node_browser
node_launcher_app -.->|"starts or stops"| node_server
node_server -->|"exposes remotely"| node_cloudflared
node_cloudflared -->|"shares link"| node_discord
node_launcher_app -.->|"sets webhook"| node_discord

click node_server "https://github.com/whimsypingu/scuttle/blob/main/backend/server.py"
click node_search_api "https://github.com/whimsypingu/scuttle/blob/main/backend/api/routers/search_router.py"
click node_playlist_api "https://github.com/whimsypingu/scuttle/blob/main/backend/api/routers/playlists_router.py"
click node_queue_api "https://github.com/whimsypingu/scuttle/blob/main/backend/api/routers/queue_router.py"
click node_audio_api "https://github.com/whimsypingu/scuttle/blob/main/backend/api/routers/audio_router.py"
click node_ws_api "https://github.com/whimsypingu/scuttle/blob/main/backend/api/routers/websocket_router.py"
click node_database "https://github.com/whimsypingu/scuttle/blob/main/backend/core/database/audio_database.py"
click node_youtube "https://github.com/whimsypingu/scuttle/blob/main/backend/core/youtube/client.py"
click node_download_worker "https://github.com/whimsypingu/scuttle/blob/main/backend/core/worker/download.py"
click node_download_queue "https://github.com/whimsypingu/scuttle/blob/main/backend/core/queue/implementations/download_queue.py"
click node_processor "https://github.com/whimsypingu/scuttle/blob/main/backend/core/audio/processor.py"
click node_play_queue "https://github.com/whimsypingu/scuttle/blob/main/backend/core/queue/implementations/play_queue.py"
click node_stream "https://github.com/whimsypingu/scuttle/blob/main/backend/core/audio/stream.py"
click node_playlist_manager "https://github.com/whimsypingu/scuttle/blob/main/backend/core/playlists/manager.py"
click node_spotify_import "https://github.com/whimsypingu/scuttle/blob/main/backend/core/playlists/implementations/spotify_playlist_ext.py"
click node_enrich_worker "https://github.com/whimsypingu/scuttle/blob/main/backend/core/worker/enrich.py"
click node_musicbrainz "https://github.com/whimsypingu/scuttle/blob/main/backend/core/musicbrainz/client.py"
click node_event_bus "https://github.com/whimsypingu/scuttle/blob/main/backend/core/events/event_bus.py"
click node_event_handlers "https://github.com/whimsypingu/scuttle/blob/main/backend/core/events/handlers.py"
click node_ws_manager "https://github.com/whimsypingu/scuttle/blob/main/backend/core/events/websocket/manager.py"
click node_frontend_main "https://github.com/whimsypingu/scuttle/blob/main/frontend/js/main.js"
click node_search_ui "https://github.com/whimsypingu/scuttle/blob/main/frontend/js/features/search/controller.js"
click node_audio_ui "https://github.com/whimsypingu/scuttle/blob/main/frontend/js/features/audio/controller.js"
click node_queue_ui "https://github.com/whimsypingu/scuttle/blob/main/frontend/js/features/queue/controller.js"
click node_playlist_ui "https://github.com/whimsypingu/scuttle/blob/main/frontend/js/features/playlist/controller.js"
click node_popup_ui "https://github.com/whimsypingu/scuttle/blob/main/frontend/js/features/popup/controller.js"
click node_client_stores "https://github.com/whimsypingu/scuttle/blob/main/frontend/js/cache/TrackStore.js"
click node_ws_client "https://github.com/whimsypingu/scuttle/blob/main/frontend/js/events/websocket/handlers.js"
click node_launcher_app "https://github.com/whimsypingu/scuttle/blob/main/launcher/src/app.rs"

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_server,node_search_api,node_playlist_api,node_queue_api,node_audio_api,node_ws_api,node_database,node_youtube,node_download_worker,node_download_queue,node_processor,node_play_queue,node_stream,node_playlist_manager,node_spotify_import,node_enrich_worker,node_musicbrainz,node_event_bus,node_event_handlers,node_ws_manager,node_browser toneBlue
class node_frontend_main,node_search_ui,node_audio_ui,node_queue_ui,node_playlist_ui,node_popup_ui,node_client_stores,node_ws_client toneAmber
class node_launcher_app,node_discord toneMint
class node_user,node_cloudflared toneIndigo
```

## Components

### Backend services

- [FastAPI server](https://github.com/whimsypingu/scuttle/blob/main/backend/server.py): `backend/server.py`
- [Search API](https://github.com/whimsypingu/scuttle/blob/main/backend/api/routers/search_router.py): `backend/api/routers/search_router.py`
- [Playlist API](https://github.com/whimsypingu/scuttle/blob/main/backend/api/routers/playlists_router.py): `backend/api/routers/playlists_router.py`
- [Queue API](https://github.com/whimsypingu/scuttle/blob/main/backend/api/routers/queue_router.py): `backend/api/routers/queue_router.py`
- [Audio API](https://github.com/whimsypingu/scuttle/blob/main/backend/api/routers/audio_router.py): `backend/api/routers/audio_router.py`
- [WebSocket API](https://github.com/whimsypingu/scuttle/blob/main/backend/api/routers/websocket_router.py): `backend/api/routers/websocket_router.py`
- [Audio library](https://github.com/whimsypingu/scuttle/blob/main/backend/core/database/audio_database.py): `backend/core/database/audio_database.py`
- [Audio discovery](https://github.com/whimsypingu/scuttle/blob/main/backend/core/youtube/client.py): `backend/core/youtube/client.py`
- [Download worker](https://github.com/whimsypingu/scuttle/blob/main/backend/core/worker/download.py): `backend/core/worker/download.py`
- [Download queue](https://github.com/whimsypingu/scuttle/blob/main/backend/core/queue/implementations/download_queue.py): `backend/core/queue/implementations/download_queue.py`
- [Audio processing](https://github.com/whimsypingu/scuttle/blob/main/backend/core/audio/processor.py): `backend/core/audio/processor.py`
- [Playback queue](https://github.com/whimsypingu/scuttle/blob/main/backend/core/queue/implementations/play_queue.py): `backend/core/queue/implementations/play_queue.py`
- [Audio streaming](https://github.com/whimsypingu/scuttle/blob/main/backend/core/audio/stream.py): `backend/core/audio/stream.py`
- [Playlist manager](https://github.com/whimsypingu/scuttle/blob/main/backend/core/playlists/manager.py): `backend/core/playlists/manager.py`
- [Spotify import](https://github.com/whimsypingu/scuttle/blob/main/backend/core/playlists/implementations/spotify_playlist_ext.py): `backend/core/playlists/implementations/spotify_playlist_ext.py`
- [Metadata enrichment](https://github.com/whimsypingu/scuttle/blob/main/backend/core/worker/enrich.py): `backend/core/worker/enrich.py`
- [MusicBrainz client](https://github.com/whimsypingu/scuttle/blob/main/backend/core/musicbrainz/client.py): `backend/core/musicbrainz/client.py`
- [Event bus](https://github.com/whimsypingu/scuttle/blob/main/backend/core/events/event_bus.py): `backend/core/events/event_bus.py`
- [Event handlers](https://github.com/whimsypingu/scuttle/blob/main/backend/core/events/handlers.py): `backend/core/events/handlers.py`
- [WebSocket manager](https://github.com/whimsypingu/scuttle/blob/main/backend/core/events/websocket/manager.py): `backend/core/events/websocket/manager.py`

### Browser client

- [Client bootstrap](https://github.com/whimsypingu/scuttle/blob/main/frontend/js/main.js): `frontend/js/main.js`
- [Search interface](https://github.com/whimsypingu/scuttle/blob/main/frontend/js/features/search/controller.js): `frontend/js/features/search/controller.js`
- [Playback controls](https://github.com/whimsypingu/scuttle/blob/main/frontend/js/features/audio/controller.js): `frontend/js/features/audio/controller.js`
- [Queue interface](https://github.com/whimsypingu/scuttle/blob/main/frontend/js/features/queue/controller.js): `frontend/js/features/queue/controller.js`
- [Playlist interface](https://github.com/whimsypingu/scuttle/blob/main/frontend/js/features/playlist/controller.js): `frontend/js/features/playlist/controller.js`
- [Playlist dialogs](https://github.com/whimsypingu/scuttle/blob/main/frontend/js/features/popup/controller.js): `frontend/js/features/popup/controller.js`
- [Client state](https://github.com/whimsypingu/scuttle/blob/main/frontend/js/cache/TrackStore.js): `frontend/js/cache/TrackStore.js`
- [Live updates](https://github.com/whimsypingu/scuttle/blob/main/frontend/js/events/websocket/handlers.js): `frontend/js/events/websocket/handlers.js`

### Desktop launcher

- [Desktop controls](https://github.com/whimsypingu/scuttle/blob/main/launcher/src/app.rs): `launcher/src/app.rs`

### Other components

- **Listener**
- **Web browser**
- **Cloudflared tunnel**
- **Discord webhook**

## Connections

- Listener → Web browser: uses
- Web browser → FastAPI server: REST requests
- FastAPI server → Web browser: WebSocket events
- FastAPI server → Search API: routes to (evidence: `backend/server.py`)
- Search API → Audio library: searches (evidence: `backend/api/routers/search_router.py`)
- Search API → Audio discovery: deep searches (evidence: `backend/api/routers/search_router.py`)
- Search API → Download queue: enqueues job
- FastAPI server → Playlist API: routes to (evidence: `backend/server.py`)
- Playlist API → Audio library: reads library (evidence: `backend/api/routers/playlists_router.py`)
- Playlist API → Playlist manager: uses (evidence: `backend/api/routers/playlists_router.py`)
- FastAPI server → Queue API: routes to (evidence: `backend/server.py`)
- FastAPI server → Audio API: routes to (evidence: `backend/server.py`)
- FastAPI server → WebSocket API: routes to (evidence: `backend/server.py`)
- FastAPI server → Audio library: initializes (evidence: `backend/server.py`)
- FastAPI server → Download worker: starts (evidence: `backend/server.py`)
- FastAPI server → Download queue: configures (evidence: `backend/server.py`)
- FastAPI server → Playback queue: configures (evidence: `backend/server.py`)
- FastAPI server → Metadata enrichment: starts (evidence: `backend/server.py`)
- FastAPI server → Audio processing: configures (evidence: `backend/server.py`)
- FastAPI server → Audio discovery: configures (evidence: `backend/server.py`)
- FastAPI server → MusicBrainz client: configures (evidence: `backend/server.py`)
- FastAPI server → Event bus: configures (evidence: `backend/server.py`)
- FastAPI server → Event handlers: registers (evidence: `backend/server.py`)
- FastAPI server → WebSocket manager: configures (evidence: `backend/server.py`)
- Download worker → Audio discovery: downloads
- Download worker → Audio processing: processes audio
- Download worker → Audio library: registers tracks
- Metadata enrichment → MusicBrainz client: enriches from
- Metadata enrichment → Audio library: updates metadata
- Playlist manager → Spotify import: delegates to (evidence: `backend/core/playlists/manager.py`)
- Audio library → Event bus: publishes events (evidence: `backend/core/database/audio_database.py`)
- Event handlers → Event bus: subscribes (evidence: `backend/core/events/handlers.py`)
- Event handlers → WebSocket manager: broadcasts (evidence: `backend/core/events/handlers.py`)
- Client bootstrap → Search interface: initializes
- Search interface → FastAPI server: searches and queues
- Playback controls → Queue interface: controls playback (evidence: `frontend/js/features/audio/controller.js`)
- Playlist interface → Playback controls: loads tracks (evidence: `frontend/js/features/playlist/controller.js`)
- Playlist interface → Queue interface: adds tracks (evidence: `frontend/js/features/playlist/controller.js`)
- Playlist interface → Client state: updates state (evidence: `frontend/js/features/playlist/controller.js`)
- Playlist dialogs → Playlist interface: renders playlists (evidence: `frontend/js/features/popup/controller.js`)
- Playlist dialogs → FastAPI server: deletes playlists
- Live updates → Client state: updates state (evidence: `frontend/js/events/websocket/handlers.js`)
- Live updates → Web browser: refreshes interface (evidence: `frontend/js/events/websocket/handlers.js`)
- Desktop controls → FastAPI server: starts or stops
- FastAPI server → Cloudflared tunnel: exposes remotely
- Cloudflared tunnel → Discord webhook: shares link
- Desktop controls → Discord webhook: sets webhook
