# jeffvli/feishin architecture

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

- Interactive diagram: https://gitdiagram.com/jeffvli/feishin
- Repository: https://github.com/jeffvli/feishin

## Overview

Feishin is a self-hosted music client for Jellyfin, Navidrome, and Subsonic servers, packaged as a desktop app and also offered as a web client. The typical workflow is to connect to a music server, browse its library, and play music through a selected player backend; lyrics, playlists, and a phone-friendly remote are additional capabilities. The graph combines README-documented product flows with source-index relationships and shown IPC/API calls. Some feature wiring is unsampled, so uncertain links are omitted or dashed.

Main entry points: [`src/renderer/app.tsx`](https://github.com/jeffvli/feishin/blob/development/src/renderer/app.tsx) (Desktop renderer), [`src/renderer/features/player/audio-player`](https://github.com/jeffvli/feishin/tree/development/src/renderer/features/player/audio-player) (Player controls), [`src/main/index.ts`](https://github.com/jeffvli/feishin/blob/development/src/main/index.ts) (Desktop process), [`src/preload/index.ts`](https://github.com/jeffvli/feishin/blob/development/src/preload/index.ts) (Preload bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client experience"]
  node_renderer["Desktop renderer<br/>[app.tsx]"]
  node_webclient["Web client<br/>[app.tsx]"]
  node_serverconfig["Server connection"]
end

subgraph group_library["Music library"]
  node_api["Server API adapters"]
  node_albums["Albums"]
  node_artists["Artists"]
  node_playlists["Playlists"]
  node_lyrics["Lyrics"]
end

subgraph group_playback["Playback and desktop"]
  node_player["Player controls"]
  node_webengine["Web player"]
  node_mpvengine["MPV player"]
  node_dlnaengine["DLNA player"]
  node_preload["Preload bridge<br/>[index.ts]"]
  node_main["Desktop process<br/>[index.ts]"]
  node_settings[("Settings and secrets<br/>[index.ts]")]
  node_media["Media keys<br/>[media-keys.ts]"]
end

subgraph group_remote["Remote access"]
  node_remoteui["Remote interface"]
  node_remotesvc["Remote service<br/>[index.ts]"]
  node_remotebridge["Remote IPC bridge<br/>[remote.ts]"]
end

node_user(("Listener"))
node_musicserver[("Music server")]

node_user -->|"uses"| node_renderer
node_user -->|"uses"| node_webclient
node_renderer -.->|"configures"| node_serverconfig
node_serverconfig -.->|"selects server"| node_api
node_api -->|"requests library"| node_musicserver
node_renderer -.->|"browses"| node_albums
node_renderer -.->|"browses"| node_artists
node_renderer -->|"edits playlists"| node_playlists
node_renderer -->|"shows lyrics"| node_lyrics
node_renderer -.->|"controls playback"| node_player
node_player -->|"selects backend"| node_webengine
node_player -->|"selects backend"| node_mpvengine
node_player -.->|"selects device"| node_dlnaengine
node_mpvengine -.->|"uses bridge"| node_preload
node_dlnaengine -.->|"uses bridge"| node_preload
node_main -->|"configures preload"| node_preload
node_main -->|"initializes"| node_settings
node_main -->|"imports feature"| node_media
node_media -->|"reads preferences"| node_settings
node_webclient -.->|"renders"| node_remoteui
node_remoteui -.->|"sends requests"| node_remotebridge
node_remotebridge -->|"IPC requests"| node_remotesvc
node_remotesvc -.->|"proxies requests"| node_musicserver

click node_renderer "https://github.com/jeffvli/feishin/blob/development/src/renderer/app.tsx"
click node_webclient "https://github.com/jeffvli/feishin/blob/development/src/remote/app.tsx"
click node_serverconfig "https://github.com/jeffvli/feishin/tree/development/src/renderer/features/action-required"
click node_api "https://github.com/jeffvli/feishin/tree/development/src/renderer/api"
click node_albums "https://github.com/jeffvli/feishin/tree/development/src/renderer/features/albums"
click node_artists "https://github.com/jeffvli/feishin/tree/development/src/renderer/features/artists"
click node_playlists "https://github.com/jeffvli/feishin/tree/development/src/renderer/features/playlists"
click node_lyrics "https://github.com/jeffvli/feishin/tree/development/src/renderer/features/lyrics"
click node_player "https://github.com/jeffvli/feishin/tree/development/src/renderer/features/player/audio-player"
click node_webengine "https://github.com/jeffvli/feishin/blob/development/src/renderer/features/player/audio-player/engine/web-player-engine.tsx"
click node_mpvengine "https://github.com/jeffvli/feishin/blob/development/src/renderer/features/player/audio-player/engine/mpv-player-engine.tsx"
click node_dlnaengine "https://github.com/jeffvli/feishin/blob/development/src/renderer/features/player/audio-player/engine/dlna-player-engine.tsx"
click node_preload "https://github.com/jeffvli/feishin/blob/development/src/preload/index.ts"
click node_main "https://github.com/jeffvli/feishin/blob/development/src/main/index.ts"
click node_settings "https://github.com/jeffvli/feishin/blob/development/src/main/features/core/settings/index.ts"
click node_media "https://github.com/jeffvli/feishin/blob/development/src/main/features/core/player/media-keys.ts"
click node_remoteui "https://github.com/jeffvli/feishin/blob/development/src/remote/components/remote-container.tsx"
click node_remotesvc "https://github.com/jeffvli/feishin/blob/development/src/main/features/core/remote/index.ts"
click node_remotebridge "https://github.com/jeffvli/feishin/blob/development/src/preload/remote.ts"

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_renderer,node_webclient,node_serverconfig toneBlue
class node_api,node_albums,node_artists,node_playlists,node_lyrics,node_musicserver toneAmber
class node_player,node_webengine,node_mpvengine,node_dlnaengine,node_preload,node_main,node_settings,node_media toneMint
class node_remoteui,node_remotesvc,node_remotebridge toneRose
class node_user toneIndigo
```

## Components

### Client experience

- [Desktop renderer](https://github.com/jeffvli/feishin/blob/development/src/renderer/app.tsx): `src/renderer/app.tsx`
- [Web client](https://github.com/jeffvli/feishin/blob/development/src/remote/app.tsx): `src/remote/app.tsx`
- [Server connection](https://github.com/jeffvli/feishin/tree/development/src/renderer/features/action-required): `src/renderer/features/action-required`

### Music library

- [Server API adapters](https://github.com/jeffvli/feishin/tree/development/src/renderer/api): `src/renderer/api`
- [Albums](https://github.com/jeffvli/feishin/tree/development/src/renderer/features/albums): `src/renderer/features/albums`
- [Artists](https://github.com/jeffvli/feishin/tree/development/src/renderer/features/artists): `src/renderer/features/artists`
- [Playlists](https://github.com/jeffvli/feishin/tree/development/src/renderer/features/playlists): `src/renderer/features/playlists`
- [Lyrics](https://github.com/jeffvli/feishin/tree/development/src/renderer/features/lyrics): `src/renderer/features/lyrics`

### Playback and desktop

- [Player controls](https://github.com/jeffvli/feishin/tree/development/src/renderer/features/player/audio-player): `src/renderer/features/player/audio-player`
- [Web player](https://github.com/jeffvli/feishin/blob/development/src/renderer/features/player/audio-player/engine/web-player-engine.tsx): `src/renderer/features/player/audio-player/engine/web-player-engine.tsx`
- [MPV player](https://github.com/jeffvli/feishin/blob/development/src/renderer/features/player/audio-player/engine/mpv-player-engine.tsx): `src/renderer/features/player/audio-player/engine/mpv-player-engine.tsx`
- [DLNA player](https://github.com/jeffvli/feishin/blob/development/src/renderer/features/player/audio-player/engine/dlna-player-engine.tsx): `src/renderer/features/player/audio-player/engine/dlna-player-engine.tsx`
- [Preload bridge](https://github.com/jeffvli/feishin/blob/development/src/preload/index.ts): `src/preload/index.ts`
- [Desktop process](https://github.com/jeffvli/feishin/blob/development/src/main/index.ts): `src/main/index.ts`
- [Settings and secrets](https://github.com/jeffvli/feishin/blob/development/src/main/features/core/settings/index.ts): `src/main/features/core/settings/index.ts`
- [Media keys](https://github.com/jeffvli/feishin/blob/development/src/main/features/core/player/media-keys.ts): `src/main/features/core/player/media-keys.ts`

### Remote access

- [Remote interface](https://github.com/jeffvli/feishin/blob/development/src/remote/components/remote-container.tsx): `src/remote/components/remote-container.tsx`
- [Remote service](https://github.com/jeffvli/feishin/blob/development/src/main/features/core/remote/index.ts): `src/main/features/core/remote/index.ts`
- [Remote IPC bridge](https://github.com/jeffvli/feishin/blob/development/src/preload/remote.ts): `src/preload/remote.ts`

### Other components

- **Listener**
- **Music server**

## Connections

- Listener → Desktop renderer: uses (evidence: `README.md`)
- Listener → Web client: uses (evidence: `README.md`)
- Desktop renderer → Server connection: configures
- Server connection → Server API adapters: selects server
- Server API adapters → Music server: requests library (evidence: `README.md`)
- Desktop renderer → Albums: browses
- Desktop renderer → Artists: browses
- Desktop renderer → Playlists: edits playlists (evidence: `README.md`)
- Desktop renderer → Lyrics: shows lyrics (evidence: `README.md`)
- Desktop renderer → Player controls: controls playback
- Player controls → Web player: selects backend (evidence: `README.md`)
- Player controls → MPV player: selects backend (evidence: `README.md`)
- Player controls → DLNA player: selects device (evidence: `src/renderer/features/player/audio-player/engine/dlna-player-engine.tsx`)
- MPV player → Preload bridge: uses bridge
- DLNA player → Preload bridge: uses bridge
- Desktop process → Preload bridge: configures preload (evidence: `src/main/index.ts`)
- Desktop process → Settings and secrets: initializes (evidence: `src/main/index.ts`)
- Desktop process → Media keys: imports feature (evidence: `src/main/index.ts`)
- Media keys → Settings and secrets: reads preferences (evidence: `src/main/features/core/player/media-keys.ts`)
- Web client → Remote interface: renders
- Remote interface → Remote IPC bridge: sends requests
- Remote IPC bridge → Remote service: IPC requests (evidence: `src/preload/remote.ts`)
- Remote service → Music server: proxies requests
