# heiphaistos/forge-audio- architecture

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

- Interactive diagram: https://gitdiagram.com/heiphaistos/forge-audio-
- Repository: https://github.com/heiphaistos/forge-audio-

## Overview

Forge Audio is a self-hosted, multi-source music player with web and Electron clients. The main workflow is discovery or link import, server-side media resolution, then client playback; library state can persist locally or sync across devices. The graph also preserves the documented radio, lyrics, catalog, social, account, download, and desktop capabilities. Several server and UI subsystems are represented by their exact paths but were not sampled; their documented capabilities are shown without asserting unverified internal calls.

Main entry points: [`server/src/app.js`](https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/server/src/app.js) (HTTP API routes), [`web/src/lib/api.ts`](https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/web/src/lib/api.ts) (Web API client), [`desktop/main.js`](https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/desktop/main.js) (Electron host), [`web/src/store/player.ts`](https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/web/src/store/player.ts) (Queue and player state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web experience"]
  node_app["App and navigation<br/>[App.tsx]"]
  node_searchui["Search and browse<br/>[Search.tsx]"]
  node_catalogui["Catalog views<br/>[Catalog.tsx]"]
  node_radio_ui["Radio view<br/>[Radio.tsx]"]
  node_library["Library state<br/>[library.ts]"]
  node_player["Queue and player state<br/>[player.ts]"]
  node_api["Web API client<br/>[api.ts]"]
  node_sync["Cross-device sync<br/>[sync.ts]"]
  node_social_ui["Social and Jam<br/>[social.ts]"]
end

subgraph group_playback["Music discovery and playback"]
  node_audio["Audio engine<br/>[engine.ts]"]
end

subgraph group_server["Server services"]
  node_server_app["HTTP API routes<br/>[app.js]"]
  node_accounts[("Accounts and sessions<br/>[accounts.js]")]
  node_search["Source search<br/>[search.js]"]
  node_ytdlp["Media source resolver<br/>[ytdlp.js]"]
  node_streaming["Playback resolution<br/>[streaming.js]"]
  node_stream["Media streaming<br/>[stream.js]"]
  node_radio["Radio service<br/>[radio.js]"]
  node_lyrics["Lyrics service<br/>[lyrics.js]"]
  node_catalog["Music catalog<br/>[catalog.js]"]
  node_userdata[("User library data<br/>[userdata.js]")]
  node_social["Social services<br/>[social.js]"]
end

subgraph group_desktop["Desktop runtime"]
  node_desktop_main["Electron host<br/>[main.js]"]
  node_desktop_ytdlp["Desktop yt-dlp manager<br/>[ytdlp-manager.js]"]
  node_desktop_updater["Desktop updater<br/>[updater.js]"]
end

node_listener(("Listener"))
node_external_sources["Music source sites"]
node_lrclib["LRCLIB"]

node_listener -->|"uses"| node_app
node_app -->|"routes to"| node_searchui
node_listener -->|"searches"| node_searchui
node_searchui -->|"requests search"| node_api
node_api -->|"calls API"| node_server_app
node_server_app -->|"dispatches search"| node_search
node_search -->|"queries sources"| node_ytdlp
node_ytdlp -->|"extracts media"| node_external_sources
node_listener -->|"controls playback"| node_player
node_player -->|"loads and controls"| node_audio
node_audio -->|"resolves tracks"| node_api
node_api -->|"requests resolution"| node_server_app
node_server_app -->|"resolves playback"| node_streaming
node_streaming -->|"resolves media URL"| node_ytdlp
node_server_app -->|"serves media"| node_stream
node_player -->|"updates listening state"| node_library
node_library -->|"syncs library state"| node_sync
node_sync -->|"reads and writes data"| node_api
node_server_app -->|"persists user data"| node_userdata
node_server_app -->|"authenticates users"| node_accounts
node_listener -->|"browses catalog"| node_catalogui
node_catalogui -->|"requests catalog"| node_api
node_server_app -->|"serves catalog"| node_catalog
node_listener -->|"starts radio"| node_radio_ui
node_radio_ui -->|"requests stations"| node_api
node_server_app -->|"routes radio"| node_radio
node_server_app -->|"serves lyrics"| node_lyrics
node_lyrics -->|"looks up lyrics"| node_lrclib
node_listener -->|"uses social features"| node_social_ui
node_social_ui -->|"sends social requests"| node_api
node_server_app -->|"routes social features"| node_social
node_listener -->|"uses desktop app"| node_desktop_main
node_desktop_main -->|"starts embedded server"| node_server_app
node_desktop_main -->|"manages yt-dlp"| node_desktop_ytdlp
node_desktop_main -->|"checks updates"| node_desktop_updater

click node_app "https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/web/src/App.tsx"
click node_searchui "https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/web/src/views/Search.tsx"
click node_catalogui "https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/web/src/views/Catalog.tsx"
click node_radio_ui "https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/web/src/views/Radio.tsx"
click node_library "https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/web/src/store/library.ts"
click node_player "https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/web/src/store/player.ts"
click node_audio "https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/web/src/audio/engine.ts"
click node_api "https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/web/src/lib/api.ts"
click node_sync "https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/web/src/lib/sync.ts"
click node_social_ui "https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/web/src/store/social.ts"
click node_server_app "https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/server/src/app.js"
click node_accounts "https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/server/src/accounts.js"
click node_search "https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/server/src/search.js"
click node_ytdlp "https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/server/src/ytdlp.js"
click node_streaming "https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/server/src/streaming.js"
click node_stream "https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/server/src/stream.js"
click node_radio "https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/server/src/radio.js"
click node_lyrics "https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/server/src/lyrics.js"
click node_catalog "https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/server/src/catalog.js"
click node_userdata "https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/server/src/userdata.js"
click node_social "https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/server/src/social.js"
click node_desktop_main "https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/desktop/main.js"
click node_desktop_ytdlp "https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/desktop/ytdlp-manager.js"
click node_desktop_updater "https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/desktop/updater.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_searchui,node_catalogui,node_radio_ui,node_library,node_player,node_api,node_sync,node_social_ui toneBlue
class node_audio toneAmber
class node_server_app,node_accounts,node_search,node_ytdlp,node_streaming,node_stream,node_radio,node_lyrics,node_catalog,node_userdata,node_social toneMint
class node_desktop_main,node_desktop_ytdlp,node_desktop_updater toneRose
class node_listener,node_external_sources,node_lrclib toneIndigo
```

## Components

### Web experience

- [App and navigation](https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/web/src/App.tsx): `web/src/App.tsx`
- [Search and browse](https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/web/src/views/Search.tsx): `web/src/views/Search.tsx`
- [Catalog views](https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/web/src/views/Catalog.tsx): `web/src/views/Catalog.tsx`
- [Radio view](https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/web/src/views/Radio.tsx): `web/src/views/Radio.tsx`
- [Library state](https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/web/src/store/library.ts): `web/src/store/library.ts`
- [Queue and player state](https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/web/src/store/player.ts): `web/src/store/player.ts`
- [Web API client](https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/web/src/lib/api.ts): `web/src/lib/api.ts`
- [Cross-device sync](https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/web/src/lib/sync.ts): `web/src/lib/sync.ts`
- [Social and Jam](https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/web/src/store/social.ts): `web/src/store/social.ts`

### Music discovery and playback

- [Audio engine](https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/web/src/audio/engine.ts): `web/src/audio/engine.ts`

### Server services

- [HTTP API routes](https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/server/src/app.js): `server/src/app.js`
- [Accounts and sessions](https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/server/src/accounts.js): `server/src/accounts.js`
- [Source search](https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/server/src/search.js): `server/src/search.js`
- [Media source resolver](https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/server/src/ytdlp.js): `server/src/ytdlp.js`
- [Playback resolution](https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/server/src/streaming.js): `server/src/streaming.js`
- [Media streaming](https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/server/src/stream.js): `server/src/stream.js`
- [Radio service](https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/server/src/radio.js): `server/src/radio.js`
- [Lyrics service](https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/server/src/lyrics.js): `server/src/lyrics.js`
- [Music catalog](https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/server/src/catalog.js): `server/src/catalog.js`
- [User library data](https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/server/src/userdata.js): `server/src/userdata.js`
- [Social services](https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/server/src/social.js): `server/src/social.js`

### Desktop runtime

- [Electron host](https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/desktop/main.js): `desktop/main.js`
- [Desktop yt-dlp manager](https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/desktop/ytdlp-manager.js): `desktop/ytdlp-manager.js`
- [Desktop updater](https://github.com/heiphaistos/forge-audio-/blob/claude/forge-audio-app-37ak3n/desktop/updater.js): `desktop/updater.js`

### Other components

- **Listener**
- **Music source sites**
- **LRCLIB**

## Connections

- Listener → App and navigation: uses (evidence: `README.md`)
- App and navigation → Search and browse: routes to (evidence: `web/src/App.tsx`)
- Listener → Search and browse: searches (evidence: `README.md`)
- Search and browse → Web API client: requests search (evidence: `web/src/views/Search.tsx`)
- Web API client → HTTP API routes: calls API (evidence: `README.md`)
- HTTP API routes → Source search: dispatches search (evidence: `server/src/app.js`)
- Source search → Media source resolver: queries sources (evidence: `server/src/search.js`)
- Media source resolver → Music source sites: extracts media (evidence: `README.md`)
- Listener → Queue and player state: controls playback (evidence: `README.md`)
- Queue and player state → Audio engine: loads and controls (evidence: `web/src/store/player.ts`)
- Audio engine → Web API client: resolves tracks (evidence: `web/src/audio/engine.ts`)
- Web API client → HTTP API routes: requests resolution (evidence: `README.md`)
- HTTP API routes → Playback resolution: resolves playback (evidence: `server/src/app.js`)
- Playback resolution → Media source resolver: resolves media URL (evidence: `server/src/streaming.js`)
- HTTP API routes → Media streaming: serves media (evidence: `README.md`)
- Queue and player state → Library state: updates listening state (evidence: `web/src/store/player.ts`)
- Library state → Cross-device sync: syncs library state (evidence: `web/src/lib/sync.ts`)
- Cross-device sync → Web API client: reads and writes data (evidence: `web/src/lib/sync.ts`)
- HTTP API routes → User library data: persists user data (evidence: `server/src/app.js`)
- HTTP API routes → Accounts and sessions: authenticates users (evidence: `server/src/app.js`)
- Listener → Catalog views: browses catalog (evidence: `README.md`)
- Catalog views → Web API client: requests catalog (evidence: `web/src/views/Catalog.tsx`)
- HTTP API routes → Music catalog: serves catalog (evidence: `server/src/app.js`)
- Listener → Radio view: starts radio (evidence: `README.md`)
- Radio view → Web API client: requests stations (evidence: `web/src/views/Radio.tsx`)
- HTTP API routes → Radio service: routes radio (evidence: `server/src/app.js`)
- HTTP API routes → Lyrics service: serves lyrics (evidence: `README.md`)
- Lyrics service → LRCLIB: looks up lyrics (evidence: `README.md`)
- Listener → Social and Jam: uses social features (evidence: `README.md`)
- Social and Jam → Web API client: sends social requests (evidence: `web/src/store/social.ts`)
- HTTP API routes → Social services: routes social features (evidence: `server/src/app.js`)
- Listener → Electron host: uses desktop app (evidence: `README.md`)
- Electron host → HTTP API routes: starts embedded server (evidence: `README.md`)
- Electron host → Desktop yt-dlp manager: manages yt-dlp (evidence: `desktop/main.js`)
- Electron host → Desktop updater: checks updates (evidence: `desktop/main.js`)
