# dubeykartikay/lazyspotify architecture

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

- Interactive diagram: https://gitdiagram.com/dubeykartikay/lazyspotify
- Repository: https://github.com/dubeykartikay/lazyspotify

## Overview

lazyspotify is a terminal Spotify client. Its principal workflow is to authenticate a user, browse or search Spotify’s library, select media, and control playback through a local librespot daemon. The UI is divided into app coordination, authentication, library browsing, and player/display components; internal layers handle Spotify API access and daemon-backed playback. The README documents demos and capabilities, while sampled source and the SOURCE INDEX support only some internal call links, so undocumented relationships are omitted.

Main entry points: [`ui/v1/app/model.go`](https://github.com/dubeykartikay/lazyspotify/blob/main/ui/v1/app/model.go) (TUI coordinator), [`core/auth/auth.go`](https://github.com/dubeykartikay/lazyspotify/blob/main/core/auth/auth.go) (Auth orchestration), [`cmd/lazyspotify/main.go`](https://github.com/dubeykartikay/lazyspotify/blob/main/cmd/lazyspotify/main.go) (Program entry), [`core/player/player.go`](https://github.com/dubeykartikay/lazyspotify/blob/main/core/player/player.go) (Playback controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application entry"]
  node_main["Program entry<br/>[main.go]"]
  node_cli["CLI commands<br/>[cli.go]"]
end

subgraph group_identity["Authentication"]
  node_auth["Auth orchestration<br/>[auth.go]"]
  node_auth_server["OAuth callback server<br/>[auth_server.go]"]
  node_auth_service["OAuth service<br/>[auth_service.go]"]
  node_keyring["Token keyring<br/>[keyring.go]"]
end

subgraph group_experience["Terminal interface"]
  node_app["TUI coordinator<br/>[model.go]"]
  node_auth_ui["Auth screen<br/>[update.go]"]
  node_media_center["Media center<br/>[model.go]"]
  node_media_panel["Library panels<br/>[update.go]"]
  node_media_list["Media lists<br/>[update.go]"]
  node_display["Now playing display<br/>[update.go]"]
  node_player_view["Player interface<br/>[view.go]"]
end

subgraph group_services["Spotify and playback"]
  node_spotify_client["Spotify API client<br/>[client.go]"]
  node_player["Playback controller<br/>[player.go]"]
  node_librespot_client["Playback API client<br/>[api_client.go]"]
  node_librespot["Daemon integration<br/>[librespot.go]"]
end

subgraph group_runtime["Runtime support"]
  node_daemon_manager["Daemon manager<br/>[daemon_manager.go]"]
  node_daemon_process["Daemon process<br/>[daemon.go]"]
  node_config["App configuration<br/>[app_config.go]"]
end

node_user(("User"))
node_spotify_service(("Spotify service"))
node_daemon_service(("Librespot daemon"))

node_user -->|"starts"| node_main
node_main -->|"dispatches"| node_cli
node_main -->|"starts TUI"| node_app
node_user -->|"authenticates"| node_auth_ui
node_app -->|"coordinates"| node_auth_ui
node_app -->|"coordinates"| node_media_center
node_media_center -->|"uses"| node_media_panel
node_media_panel -->|"updates"| node_media_list
node_app -->|"uses"| node_display
node_app -->|"uses"| node_player_view
node_auth_ui -->|"requests auth"| node_auth
node_auth -->|"starts callback"| node_auth_server
node_auth -->|"obtains tokens"| node_auth_service
node_auth -->|"reads and saves tokens"| node_keyring
node_auth_service -.->|"OAuth"| node_spotify_service
node_app -->|"requests library data"| node_spotify_client
node_spotify_client -->|"queries API"| node_spotify_service
node_app -->|"controls playback"| node_player
node_player -->|"initializes"| node_librespot
node_player -->|"sends controls"| node_librespot_client
node_librespot_client -->|"HTTP requests"| node_daemon_service
node_librespot -->|"manages daemon"| node_daemon_manager
node_daemon_manager -->|"starts and monitors"| node_daemon_process
node_daemon_process -.->|"runs process"| node_daemon_service
node_main -->|"validates startup"| node_config
node_auth -->|"reads settings"| node_config

click node_main "https://github.com/dubeykartikay/lazyspotify/blob/main/cmd/lazyspotify/main.go"
click node_cli "https://github.com/dubeykartikay/lazyspotify/blob/main/cli/cli.go"
click node_app "https://github.com/dubeykartikay/lazyspotify/blob/main/ui/v1/app/model.go"
click node_auth_ui "https://github.com/dubeykartikay/lazyspotify/blob/main/ui/v1/auth/update.go"
click node_media_center "https://github.com/dubeykartikay/lazyspotify/blob/main/ui/v1/mediacenter/model.go"
click node_media_panel "https://github.com/dubeykartikay/lazyspotify/blob/main/ui/v1/mediapanel/update.go"
click node_media_list "https://github.com/dubeykartikay/lazyspotify/blob/main/ui/v1/medialist/update.go"
click node_display "https://github.com/dubeykartikay/lazyspotify/blob/main/ui/v1/displayscreen/update.go"
click node_player_view "https://github.com/dubeykartikay/lazyspotify/blob/main/ui/v1/player/view.go"
click node_auth "https://github.com/dubeykartikay/lazyspotify/blob/main/core/auth/auth.go"
click node_auth_server "https://github.com/dubeykartikay/lazyspotify/blob/main/core/auth/auth_server.go"
click node_auth_service "https://github.com/dubeykartikay/lazyspotify/blob/main/core/auth/auth_service.go"
click node_keyring "https://github.com/dubeykartikay/lazyspotify/blob/main/core/auth/keyring.go"
click node_spotify_client "https://github.com/dubeykartikay/lazyspotify/blob/main/spotify/client.go"
click node_player "https://github.com/dubeykartikay/lazyspotify/blob/main/core/player/player.go"
click node_librespot_client "https://github.com/dubeykartikay/lazyspotify/blob/main/librespot/api_client.go"
click node_librespot "https://github.com/dubeykartikay/lazyspotify/blob/main/librespot/librespot.go"
click node_daemon_manager "https://github.com/dubeykartikay/lazyspotify/blob/main/core/daemon/daemon_manager.go"
click node_daemon_process "https://github.com/dubeykartikay/lazyspotify/blob/main/core/daemon/daemon.go"
click node_config "https://github.com/dubeykartikay/lazyspotify/blob/main/core/utils/app_config.go"

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_main,node_cli,node_user toneBlue
class node_auth,node_auth_server,node_auth_service,node_keyring toneAmber
class node_app,node_auth_ui,node_media_center,node_media_panel,node_media_list,node_display,node_player_view toneMint
class node_spotify_client,node_player,node_librespot_client,node_librespot toneRose
class node_daemon_manager,node_daemon_process,node_config,node_spotify_service,node_daemon_service toneIndigo
```

## Components

### Application entry

- [Program entry](https://github.com/dubeykartikay/lazyspotify/blob/main/cmd/lazyspotify/main.go): `cmd/lazyspotify/main.go`
- [CLI commands](https://github.com/dubeykartikay/lazyspotify/blob/main/cli/cli.go): `cli/cli.go`

### Authentication

- [Auth orchestration](https://github.com/dubeykartikay/lazyspotify/blob/main/core/auth/auth.go): `core/auth/auth.go`
- [OAuth callback server](https://github.com/dubeykartikay/lazyspotify/blob/main/core/auth/auth_server.go): `core/auth/auth_server.go`
- [OAuth service](https://github.com/dubeykartikay/lazyspotify/blob/main/core/auth/auth_service.go): `core/auth/auth_service.go`
- [Token keyring](https://github.com/dubeykartikay/lazyspotify/blob/main/core/auth/keyring.go): `core/auth/keyring.go`

### Terminal interface

- [TUI coordinator](https://github.com/dubeykartikay/lazyspotify/blob/main/ui/v1/app/model.go): `ui/v1/app/model.go`
- [Auth screen](https://github.com/dubeykartikay/lazyspotify/blob/main/ui/v1/auth/update.go): `ui/v1/auth/update.go`
- [Media center](https://github.com/dubeykartikay/lazyspotify/blob/main/ui/v1/mediacenter/model.go): `ui/v1/mediacenter/model.go`
- [Library panels](https://github.com/dubeykartikay/lazyspotify/blob/main/ui/v1/mediapanel/update.go): `ui/v1/mediapanel/update.go`
- [Media lists](https://github.com/dubeykartikay/lazyspotify/blob/main/ui/v1/medialist/update.go): `ui/v1/medialist/update.go`
- [Now playing display](https://github.com/dubeykartikay/lazyspotify/blob/main/ui/v1/displayscreen/update.go): `ui/v1/displayscreen/update.go`
- [Player interface](https://github.com/dubeykartikay/lazyspotify/blob/main/ui/v1/player/view.go): `ui/v1/player/view.go`

### Spotify and playback

- [Spotify API client](https://github.com/dubeykartikay/lazyspotify/blob/main/spotify/client.go): `spotify/client.go`
- [Playback controller](https://github.com/dubeykartikay/lazyspotify/blob/main/core/player/player.go): `core/player/player.go`
- [Playback API client](https://github.com/dubeykartikay/lazyspotify/blob/main/librespot/api_client.go): `librespot/api_client.go`
- [Daemon integration](https://github.com/dubeykartikay/lazyspotify/blob/main/librespot/librespot.go): `librespot/librespot.go`

### Runtime support

- [Daemon manager](https://github.com/dubeykartikay/lazyspotify/blob/main/core/daemon/daemon_manager.go): `core/daemon/daemon_manager.go`
- [Daemon process](https://github.com/dubeykartikay/lazyspotify/blob/main/core/daemon/daemon.go): `core/daemon/daemon.go`
- [App configuration](https://github.com/dubeykartikay/lazyspotify/blob/main/core/utils/app_config.go): `core/utils/app_config.go`

### Other components

- **User**
- **Spotify service**
- **Librespot daemon**

## Connections

- User → Program entry: starts (evidence: `README.md`)
- Program entry → CLI commands: dispatches (evidence: `cmd/lazyspotify/main.go`)
- Program entry → TUI coordinator: starts TUI (evidence: `cmd/lazyspotify/main.go`)
- User → Auth screen: authenticates (evidence: `README.md`)
- TUI coordinator → Auth screen: coordinates (evidence: `ui/v1/app/model.go`)
- TUI coordinator → Media center: coordinates (evidence: `ui/v1/app/model.go`)
- Media center → Library panels: uses (evidence: `ui/v1/mediacenter/model.go`)
- Library panels → Media lists: updates (evidence: `ui/v1/mediapanel/update.go`)
- TUI coordinator → Now playing display: uses (evidence: `ui/v1/app/model.go`)
- TUI coordinator → Player interface: uses (evidence: `ui/v1/app/model.go`)
- Auth screen → Auth orchestration: requests auth (evidence: `ui/v1/auth/update.go`)
- Auth orchestration → OAuth callback server: starts callback (evidence: `core/auth/auth.go`)
- Auth orchestration → OAuth service: obtains tokens (evidence: `core/auth/auth.go`)
- Auth orchestration → Token keyring: reads and saves tokens (evidence: `core/auth/auth.go`)
- OAuth service → Spotify service: OAuth
- TUI coordinator → Spotify API client: requests library data (evidence: `ui/v1/app/model.go`)
- Spotify API client → Spotify service: queries API (evidence: `spotify/client.go`)
- TUI coordinator → Playback controller: controls playback (evidence: `ui/v1/app/model.go`)
- Playback controller → Daemon integration: initializes (evidence: `core/player/player.go`)
- Playback controller → Playback API client: sends controls (evidence: `core/player/player.go`)
- Playback API client → Librespot daemon: HTTP requests (evidence: `librespot/api_client.go`)
- Daemon integration → Daemon manager: manages daemon (evidence: `librespot/librespot.go`)
- Daemon manager → Daemon process: starts and monitors (evidence: `core/daemon/daemon_manager.go`)
- Daemon process → Librespot daemon: runs process
- Program entry → App configuration: validates startup (evidence: `cmd/lazyspotify/main.go`)
- Auth orchestration → App configuration: reads settings (evidence: `core/auth/auth.go`)
