# ptsfdtz/litesound architecture

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

- Interactive diagram: https://gitdiagram.com/ptsfdtz/litesound
- Repository: https://github.com/ptsfdtz/litesound

## Overview

LiteSound is a desktop music-library and playback application. The main flow runs from the React interface through library and player hooks, the Wails API bridge, and Go application services; library scanning and playback use local media files, while playback audio is served through a local stream server. The README provides no feature details, so broader capabilities are reflected only where the source index or sampled files support them. Some backend subsystem links are necessarily coarse because their implementation excerpts were not provided.

Main entry points: [`frontend/src/App.tsx`](https://github.com/ptsfdtz/litesound/blob/main/frontend/src/App.tsx) (Application shell), [`internal/app/app.go`](https://github.com/ptsfdtz/litesound/blob/main/internal/app/app.go) (Application facade), [`frontend/src/hooks/usePlayer.ts`](https://github.com/ptsfdtz/litesound/blob/main/frontend/src/hooks/usePlayer.ts) (Playback engine), [`internal/library/service.go`](https://github.com/ptsfdtz/litesound/blob/main/internal/library/service.go) (Library service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Desktop interface"]
  node_app_ui["Application shell<br/>[App.tsx]"]
  node_header["Settings and window<br/>[HeaderBar.tsx]"]
  node_library_ui["Track browser<br/>[TrackList.tsx]"]
  node_filters_ui["Library filters<br/>[FiltersBar.tsx]"]
  node_playlists_ui["Playlist sidebar"]
  node_player_ui["Player controls<br/>[PlayerBar.tsx]"]
  node_update_ui["Update dialog<br/>[UpdateDialog.tsx]"]
end

subgraph group_frontend["Frontend behavior"]
  node_library_hook["Library state<br/>[useMusicLibrary.ts]"]
  node_player_hook["Playback engine<br/>[usePlayer.ts]"]
  node_queue_hook["Playback queue"]
  node_playlist_hook["Playlist state<br/>[usePlaylists.ts]"]
  node_theme_hook["Theme state<br/>[useTheme.ts]"]
  node_updater_hook["Update state<br/>[useUpdater.ts]"]
  node_api["Wails API client<br/>[api.ts]"]
  node_bindings["Generated Go bindings<br/>[App.js]"]
  node_models["Shared data models<br/>[models.ts]"]
end

subgraph group_backend["Application services"]
  node_go_app["Application facade<br/>[app.go]"]
  node_library["Library service<br/>[service.go]"]
  node_cache[("Library cache<br/>[cache.go]")]
  node_media["Media processing"]
  node_state[("Persistent state<br/>[state.go]")]
  node_updater["Update service<br/>[service.go]"]
end

subgraph group_platform["Platform integrations"]
  node_system["System features"]
end

node_user(("Listener"))
node_local_files[("Music files")]
node_wails["Wails runtime"]
node_github["GitHub releases"]

node_user -->|"uses"| node_app_ui
node_app_ui -->|"loads library"| node_library_hook
node_app_ui -->|"manages playlists"| node_playlist_hook
node_app_ui -->|"controls playback"| node_player_hook
node_app_ui -->|"builds queue"| node_queue_hook
node_app_ui -->|"reads theme"| node_theme_hook
node_app_ui -->|"checks updates"| node_updater_hook
node_app_ui -->|"renders"| node_header
node_app_ui -->|"renders"| node_library_ui
node_app_ui -->|"renders"| node_filters_ui
node_app_ui -->|"renders"| node_playlists_ui
node_app_ui -->|"renders"| node_player_ui
node_app_ui -->|"renders"| node_update_ui
node_library_hook -->|"requests library"| node_api
node_player_hook -->|"requests playback data"| node_api
node_api -->|"invokes methods"| node_bindings
node_bindings -->|"dispatches calls"| node_go_app
node_go_app -->|"constructs service"| node_library
node_go_app -->|"constructs store"| node_state
node_go_app -->|"starts platform features"| node_system
node_go_app -->|"constructs service"| node_updater
node_go_app -->|"starts stream server"| node_media
node_library -.->|"uses cache"| node_cache
node_library -.->|"scans files"| node_local_files
node_media -.->|"reads audio"| node_local_files
node_player_hook -.->|"plays stream"| node_media
node_updater -->|"fetches releases"| node_github
node_header -->|"controls window"| node_wails
node_go_app -->|"uses runtime"| node_wails

click node_app_ui "https://github.com/ptsfdtz/litesound/blob/main/frontend/src/App.tsx"
click node_header "https://github.com/ptsfdtz/litesound/blob/main/frontend/src/components/HeaderBar/HeaderBar.tsx"
click node_library_ui "https://github.com/ptsfdtz/litesound/blob/main/frontend/src/components/TrackList/TrackList.tsx"
click node_filters_ui "https://github.com/ptsfdtz/litesound/blob/main/frontend/src/components/FiltersBar/FiltersBar.tsx"
click node_playlists_ui "https://github.com/ptsfdtz/litesound/blob/main/frontend/src/components/PlaylistSidebar/PlaylistSidebar.tsx"
click node_player_ui "https://github.com/ptsfdtz/litesound/blob/main/frontend/src/components/PlayerBar/PlayerBar.tsx"
click node_update_ui "https://github.com/ptsfdtz/litesound/blob/main/frontend/src/components/UpdateDialog/UpdateDialog.tsx"
click node_library_hook "https://github.com/ptsfdtz/litesound/blob/main/frontend/src/hooks/useMusicLibrary.ts"
click node_player_hook "https://github.com/ptsfdtz/litesound/blob/main/frontend/src/hooks/usePlayer.ts"
click node_queue_hook "https://github.com/ptsfdtz/litesound/blob/main/frontend/src/hooks/usePlaybackQueue.ts"
click node_playlist_hook "https://github.com/ptsfdtz/litesound/blob/main/frontend/src/hooks/usePlaylists.ts"
click node_theme_hook "https://github.com/ptsfdtz/litesound/blob/main/frontend/src/hooks/useTheme.ts"
click node_updater_hook "https://github.com/ptsfdtz/litesound/blob/main/frontend/src/hooks/useUpdater.ts"
click node_api "https://github.com/ptsfdtz/litesound/blob/main/frontend/src/services/api.ts"
click node_bindings "https://github.com/ptsfdtz/litesound/blob/main/frontend/wailsjs/go/app/App.js"
click node_models "https://github.com/ptsfdtz/litesound/blob/main/frontend/wailsjs/go/models.ts"
click node_go_app "https://github.com/ptsfdtz/litesound/blob/main/internal/app/app.go"
click node_library "https://github.com/ptsfdtz/litesound/blob/main/internal/library/service.go"
click node_cache "https://github.com/ptsfdtz/litesound/blob/main/internal/library/cache.go"
click node_media "https://github.com/ptsfdtz/litesound/tree/main/internal/media"
click node_state "https://github.com/ptsfdtz/litesound/blob/main/internal/state/state.go"
click node_updater "https://github.com/ptsfdtz/litesound/blob/main/internal/update/service.go"
click node_system "https://github.com/ptsfdtz/litesound/tree/main/internal/system"

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_ui,node_header,node_library_ui,node_filters_ui,node_playlists_ui,node_player_ui,node_update_ui toneBlue
class node_library_hook,node_player_hook,node_queue_hook,node_playlist_hook,node_theme_hook,node_updater_hook,node_api,node_bindings,node_models,node_local_files toneAmber
class node_go_app,node_library,node_cache,node_media,node_state,node_updater toneMint
class node_system toneRose
class node_user,node_wails,node_github toneIndigo
```

## Components

### Desktop interface

- [Application shell](https://github.com/ptsfdtz/litesound/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Settings and window](https://github.com/ptsfdtz/litesound/blob/main/frontend/src/components/HeaderBar/HeaderBar.tsx): `frontend/src/components/HeaderBar/HeaderBar.tsx`
- [Track browser](https://github.com/ptsfdtz/litesound/blob/main/frontend/src/components/TrackList/TrackList.tsx): `frontend/src/components/TrackList/TrackList.tsx`
- [Library filters](https://github.com/ptsfdtz/litesound/blob/main/frontend/src/components/FiltersBar/FiltersBar.tsx): `frontend/src/components/FiltersBar/FiltersBar.tsx`
- [Playlist sidebar](https://github.com/ptsfdtz/litesound/blob/main/frontend/src/components/PlaylistSidebar/PlaylistSidebar.tsx): `frontend/src/components/PlaylistSidebar/PlaylistSidebar.tsx`
- [Player controls](https://github.com/ptsfdtz/litesound/blob/main/frontend/src/components/PlayerBar/PlayerBar.tsx): `frontend/src/components/PlayerBar/PlayerBar.tsx`
- [Update dialog](https://github.com/ptsfdtz/litesound/blob/main/frontend/src/components/UpdateDialog/UpdateDialog.tsx): `frontend/src/components/UpdateDialog/UpdateDialog.tsx`

### Frontend behavior

- [Library state](https://github.com/ptsfdtz/litesound/blob/main/frontend/src/hooks/useMusicLibrary.ts): `frontend/src/hooks/useMusicLibrary.ts`
- [Playback engine](https://github.com/ptsfdtz/litesound/blob/main/frontend/src/hooks/usePlayer.ts): `frontend/src/hooks/usePlayer.ts`
- [Playback queue](https://github.com/ptsfdtz/litesound/blob/main/frontend/src/hooks/usePlaybackQueue.ts): `frontend/src/hooks/usePlaybackQueue.ts`
- [Playlist state](https://github.com/ptsfdtz/litesound/blob/main/frontend/src/hooks/usePlaylists.ts): `frontend/src/hooks/usePlaylists.ts`
- [Theme state](https://github.com/ptsfdtz/litesound/blob/main/frontend/src/hooks/useTheme.ts): `frontend/src/hooks/useTheme.ts`
- [Update state](https://github.com/ptsfdtz/litesound/blob/main/frontend/src/hooks/useUpdater.ts): `frontend/src/hooks/useUpdater.ts`
- [Wails API client](https://github.com/ptsfdtz/litesound/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [Generated Go bindings](https://github.com/ptsfdtz/litesound/blob/main/frontend/wailsjs/go/app/App.js): `frontend/wailsjs/go/app/App.js`
- [Shared data models](https://github.com/ptsfdtz/litesound/blob/main/frontend/wailsjs/go/models.ts): `frontend/wailsjs/go/models.ts`

### Application services

- [Application facade](https://github.com/ptsfdtz/litesound/blob/main/internal/app/app.go): `internal/app/app.go`
- [Library service](https://github.com/ptsfdtz/litesound/blob/main/internal/library/service.go): `internal/library/service.go`
- [Library cache](https://github.com/ptsfdtz/litesound/blob/main/internal/library/cache.go): `internal/library/cache.go`
- [Media processing](https://github.com/ptsfdtz/litesound/tree/main/internal/media): `internal/media`
- [Persistent state](https://github.com/ptsfdtz/litesound/blob/main/internal/state/state.go): `internal/state/state.go`
- [Update service](https://github.com/ptsfdtz/litesound/blob/main/internal/update/service.go): `internal/update/service.go`

### Platform integrations

- [System features](https://github.com/ptsfdtz/litesound/tree/main/internal/system): `internal/system`

### Other components

- **Listener**
- **Music files**
- **Wails runtime**
- **GitHub releases**

## Connections

- Listener → Application shell: uses (evidence: `frontend/src/App.tsx`)
- Application shell → Library state: loads library (evidence: `frontend/src/App.tsx`)
- Application shell → Playlist state: manages playlists (evidence: `frontend/src/App.tsx`)
- Application shell → Playback engine: controls playback (evidence: `frontend/src/App.tsx`)
- Application shell → Playback queue: builds queue (evidence: `frontend/src/App.tsx`)
- Application shell → Theme state: reads theme (evidence: `frontend/src/App.tsx`)
- Application shell → Update state: checks updates (evidence: `frontend/src/App.tsx`)
- Application shell → Settings and window: renders (evidence: `frontend/src/App.tsx`)
- Application shell → Track browser: renders (evidence: `frontend/src/App.tsx`)
- Application shell → Library filters: renders (evidence: `frontend/src/App.tsx`)
- Application shell → Playlist sidebar: renders (evidence: `frontend/src/App.tsx`)
- Application shell → Player controls: renders (evidence: `frontend/src/App.tsx`)
- Application shell → Update dialog: renders (evidence: `frontend/src/App.tsx`)
- Library state → Wails API client: requests library (evidence: `frontend/src/hooks/useMusicLibrary.ts`)
- Playback engine → Wails API client: requests playback data (evidence: `frontend/src/hooks/usePlayer.ts`)
- Wails API client → Generated Go bindings: invokes methods (evidence: `frontend/src/services/api.ts`)
- Generated Go bindings → Application facade: dispatches calls (evidence: `frontend/wailsjs/go/app/App.js`)
- Application facade → Library service: constructs service (evidence: `internal/app/app.go`)
- Application facade → Persistent state: constructs store (evidence: `internal/app/app.go`)
- Application facade → System features: starts platform features (evidence: `internal/app/app.go`)
- Application facade → Update service: constructs service (evidence: `internal/app/app.go`)
- Application facade → Media processing: starts stream server (evidence: `internal/app/app.go`)
- Library service → Library cache: uses cache
- Library service → Music files: scans files
- Media processing → Music files: reads audio
- Playback engine → Media processing: plays stream
- Update service → GitHub releases: fetches releases (evidence: `internal/update/service.go`)
- Settings and window → Wails runtime: controls window (evidence: `frontend/src/components/HeaderBar/HeaderBar.tsx`)
- Application facade → Wails runtime: uses runtime (evidence: `internal/app/app.go`)