# cqink/volna architecture

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

- Interactive diagram: https://gitdiagram.com/cqink/volna
- Repository: https://github.com/cqink/volna

## Overview

Волна is a browser-based PWA music player. Users search or browse music from Audius and YouTube, then play tracks through direct audio streams or an embedded YouTube fallback; playback also supports media-session controls. Favorites and server settings are stored locally, while the service worker caches the app shell for offline startup. The excerpts are partial, so links for unsampled UI wiring and other internal stages are omitted.

Main entry points: [`app.js`](https://github.com/cqink/volna/blob/main/app.js) (App UI and logic), [`sw.js`](https://github.com/cqink/volna/blob/main/sw.js) (Shell caching)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Music discovery"]
  node_app["App UI and logic<br/>[app.js]"]
  node_audius_search["Audius search and trends<br/>[app.js]"]
  node_youtube_search["YouTube search<br/>[app.js]"]
  node_server_settings["Server settings and checks<br/>[app.js]"]
end

subgraph group_playback["Playback"]
  node_playback_control["Playback control<br/>[app.js]"]
  node_audius_stream["Audius stream resolver<br/>[app.js]"]
  node_youtube_stream["YouTube stream resolver<br/>[app.js]"]
  node_audio_element["Audio playback<br/>[app.js]"]
  node_youtube_embed["Embedded player fallback<br/>[app.js]"]
  node_media_session["Lock-screen controls<br/>[app.js]"]
end

subgraph group_pwa["PWA and state"]
  node_local_storage[("Local storage")]
  node_service_worker["Shell caching<br/>[sw.js]"]
  node_browser_cache[("Browser cache")]
end

node_listener(("Listener"))
node_audius_api{{"Audius API"}}
node_piped{{"Piped servers"}}
node_invidious{{"Invidious servers"}}
node_youtube_api{{"YouTube iframe API"}}
node_browser_media["Browser media session"]

node_listener -->|"uses"| node_app
node_app -->|"searches or browses"| node_audius_search
node_app -->|"searches"| node_youtube_search
node_audius_search -->|"requests tracks"| node_audius_api
node_youtube_search -->|"queries"| node_piped
node_youtube_search -->|"queries"| node_invidious
node_app -->|"checks servers"| node_server_settings
node_server_settings -->|"probes"| node_piped
node_server_settings -->|"probes"| node_invidious
node_app -->|"controls"| node_playback_control
node_playback_control -->|"resolves"| node_audius_stream
node_playback_control -->|"resolves"| node_youtube_stream
node_audius_stream -->|"requests stream"| node_audius_api
node_youtube_stream -->|"requests stream"| node_piped
node_youtube_stream -->|"fallback stream"| node_invidious
node_playback_control -->|"plays stream"| node_audio_element
node_playback_control -->|"falls back to"| node_youtube_embed
node_youtube_embed -->|"loads player"| node_youtube_api
node_playback_control -->|"sets metadata"| node_media_session
node_media_session -->|"registers controls"| node_browser_media
node_app -->|"reads and writes"| node_local_storage
node_service_worker -->|"caches shell"| node_browser_cache
node_browser_cache -->|"serves offline files"| node_service_worker

click node_app "https://github.com/cqink/volna/blob/main/app.js"
click node_audius_search "https://github.com/cqink/volna/blob/main/app.js"
click node_youtube_search "https://github.com/cqink/volna/blob/main/app.js"
click node_server_settings "https://github.com/cqink/volna/blob/main/app.js"
click node_playback_control "https://github.com/cqink/volna/blob/main/app.js"
click node_audius_stream "https://github.com/cqink/volna/blob/main/app.js"
click node_youtube_stream "https://github.com/cqink/volna/blob/main/app.js"
click node_audio_element "https://github.com/cqink/volna/blob/main/app.js"
click node_youtube_embed "https://github.com/cqink/volna/blob/main/app.js"
click node_media_session "https://github.com/cqink/volna/blob/main/app.js"
click node_service_worker "https://github.com/cqink/volna/blob/main/sw.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_app,node_audius_search,node_youtube_search,node_server_settings,node_browser_media toneBlue
class node_playback_control,node_audius_stream,node_youtube_stream,node_audio_element,node_youtube_embed,node_media_session toneAmber
class node_local_storage,node_service_worker,node_browser_cache,node_audius_api,node_piped,node_invidious,node_youtube_api toneMint
class node_listener toneIndigo
```

## Components

### Music discovery

- [App UI and logic](https://github.com/cqink/volna/blob/main/app.js): `app.js`
- [Audius search and trends](https://github.com/cqink/volna/blob/main/app.js): `app.js`
- [YouTube search](https://github.com/cqink/volna/blob/main/app.js): `app.js`
- [Server settings and checks](https://github.com/cqink/volna/blob/main/app.js): `app.js`

### Playback

- [Playback control](https://github.com/cqink/volna/blob/main/app.js): `app.js`
- [Audius stream resolver](https://github.com/cqink/volna/blob/main/app.js): `app.js`
- [YouTube stream resolver](https://github.com/cqink/volna/blob/main/app.js): `app.js`
- [Audio playback](https://github.com/cqink/volna/blob/main/app.js): `app.js`
- [Embedded player fallback](https://github.com/cqink/volna/blob/main/app.js): `app.js`
- [Lock-screen controls](https://github.com/cqink/volna/blob/main/app.js): `app.js`

### PWA and state

- **Local storage**
- [Shell caching](https://github.com/cqink/volna/blob/main/sw.js): `sw.js`
- **Browser cache**

### Other components

- **Listener**
- **Audius API**
- **Piped servers**
- **Invidious servers**
- **YouTube iframe API**
- **Browser media session**

## Connections

- Listener → App UI and logic: uses
- App UI and logic → Audius search and trends: searches or browses
- App UI and logic → YouTube search: searches
- Audius search and trends → Audius API: requests tracks
- YouTube search → Piped servers: queries
- YouTube search → Invidious servers: queries
- App UI and logic → Server settings and checks: checks servers
- Server settings and checks → Piped servers: probes
- Server settings and checks → Invidious servers: probes
- App UI and logic → Playback control: controls
- Playback control → Audius stream resolver: resolves
- Playback control → YouTube stream resolver: resolves
- Audius stream resolver → Audius API: requests stream
- YouTube stream resolver → Piped servers: requests stream
- YouTube stream resolver → Invidious servers: fallback stream
- Playback control → Audio playback: plays stream
- Playback control → Embedded player fallback: falls back to
- Embedded player fallback → YouTube iframe API: loads player
- Playback control → Lock-screen controls: sets metadata
- Lock-screen controls → Browser media session: registers controls
- App UI and logic → Local storage: reads and writes
- Shell caching → Browser cache: caches shell
- Browser cache → Shell caching: serves offline files