# simonepelosi/vibez architecture

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

- Interactive diagram: https://gitdiagram.com/simonepelosi/vibez
- Repository: https://github.com/simonepelosi/vibez

## Overview

vibez is a keyboard-driven terminal Apple Music player. The main workflow runs from the user through the CLI into the TUI, which searches and browses through a provider, then controls playback through a pluggable player. Apple Music supplies catalog and library data; playback may use Chrome/Widevine for full tracks or platform audio and preview backends. The README also documents vibe, discovery, and radio queue generation, lyrics, Last.fm scrobbling, MPRIS, themes, and equalizer support. Unsampled subsystem wiring is shown only where documented; several paths identify the enclosing source directory.

Main entry points: [`internal/tui/model.go`](https://github.com/simonepelosi/vibez/blob/main/internal/tui/model.go) (Terminal UI), [`internal/player/player.go`](https://github.com/simonepelosi/vibez/blob/main/internal/player/player.go) (Player interface), [`cmd/root.go`](https://github.com/simonepelosi/vibez/blob/main/cmd/root.go) (CLI commands), [`internal/provider/provider.go`](https://github.com/simonepelosi/vibez/blob/main/internal/provider/provider.go) (Provider interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["CLI and interface"]
  node_cli["CLI commands<br/>[root.go]"]
  node_tui["Terminal UI<br/>[model.go]"]
  node_views["TUI panels"]
  node_config["Settings<br/>[config.go]"]
  node_themes_eq["Themes and EQ"]
end

subgraph group_music["Music sources"]
  node_provider["Provider interface<br/>[provider.go]"]
  node_apple["Apple Music<br/>[apple.go]"]
  node_auth["MusicKit auth"]
end

subgraph group_playback["Playback"]
  node_player["Player interface<br/>[player.go]"]
  node_cdp["Chrome playback<br/>[player.go]"]
  node_browser["Chrome setup<br/>[browser.go]"]
  node_preview["Preview backends<br/>[player.go]"]
  node_local_audio["Local audio<br/>[player_darwin.go]"]
end

subgraph group_discovery["Discovery and queue"]
  node_queue["Queue controls<br/>[model.go]"]
  node_vibe["Vibe engine<br/>[agent.go]"]
  node_lyrics["Lyrics lookup<br/>[lrclib.go]"]
end

subgraph group_integrations["System integrations"]
  node_lastfm["Last.fm client<br/>[client.go]"]
  node_mpris["MPRIS bridge<br/>[server.go]"]
end

node_user(("Listener"))
node_apple_api["Apple Music API"]
node_chrome["Chrome / Widevine"]
node_lastfm_api["Last.fm API"]
node_dbus["Desktop D-Bus"]

node_user -->|"runs commands"| node_cli
node_cli -->|"starts UI"| node_tui
node_cli -->|"manages login"| node_auth
node_cli -->|"loads settings"| node_config
node_tui -->|"reads settings"| node_config
node_tui -->|"renders panels"| node_views
node_tui -->|"searches and browses"| node_provider
node_provider -->|"implemented by"| node_apple
node_apple -->|"requests catalog"| node_apple_api
node_auth -->|"authenticates"| node_apple_api
node_tui -->|"controls playback"| node_player
node_player -->|"backend"| node_cdp
node_cdp -->|"prepares browser"| node_browser
node_browser -->|"launches with DRM"| node_chrome
node_player -.->|"preview backend"| node_preview
node_player -.->|"local-file backend"| node_local_audio
node_tui -->|"manages queue"| node_queue
node_queue -->|"fetches candidates"| node_provider
node_tui -->|"parses vibe input"| node_vibe
node_tui -->|"looks up lyrics"| node_lyrics
node_tui -.->|"scrobbles listening"| node_lastfm
node_lastfm -->|"sends signed requests"| node_lastfm_api
node_player -->|"publishes playback state"| node_mpris
node_mpris -->|"exports controls"| node_dbus
node_dbus -->|"dispatches media actions"| node_mpris
node_tui -->|"provides theme and EQ panels"| node_themes_eq

click node_cli "https://github.com/simonepelosi/vibez/blob/main/cmd/root.go"
click node_tui "https://github.com/simonepelosi/vibez/blob/main/internal/tui/model.go"
click node_views "https://github.com/simonepelosi/vibez/tree/main/internal/tui/views"
click node_config "https://github.com/simonepelosi/vibez/blob/main/internal/config/config.go"
click node_provider "https://github.com/simonepelosi/vibez/blob/main/internal/provider/provider.go"
click node_apple "https://github.com/simonepelosi/vibez/blob/main/internal/provider/apple/apple.go"
click node_auth "https://github.com/simonepelosi/vibez/tree/main/internal/auth"
click node_player "https://github.com/simonepelosi/vibez/blob/main/internal/player/player.go"
click node_cdp "https://github.com/simonepelosi/vibez/blob/main/internal/player/cdp/player.go"
click node_browser "https://github.com/simonepelosi/vibez/blob/main/internal/player/cdp/browser.go"
click node_preview "https://github.com/simonepelosi/vibez/blob/main/internal/player/webkit/player.go"
click node_local_audio "https://github.com/simonepelosi/vibez/blob/main/internal/player/local/player_darwin.go"
click node_queue "https://github.com/simonepelosi/vibez/blob/main/internal/tui/model.go"
click node_vibe "https://github.com/simonepelosi/vibez/blob/main/internal/vibe/agent.go"
click node_lyrics "https://github.com/simonepelosi/vibez/blob/main/internal/lyrics/lrclib.go"
click node_lastfm "https://github.com/simonepelosi/vibez/blob/main/internal/lastfm/client.go"
click node_mpris "https://github.com/simonepelosi/vibez/blob/main/internal/player/mpris/server.go"
click node_themes_eq "https://github.com/simonepelosi/vibez/tree/main/internal/tui"

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_cli,node_tui,node_views,node_config,node_themes_eq toneBlue
class node_provider,node_apple,node_auth toneAmber
class node_player,node_cdp,node_browser,node_preview,node_local_audio,node_apple_api,node_lastfm_api toneMint
class node_queue,node_vibe,node_lyrics toneRose
class node_lastfm,node_mpris,node_user,node_chrome,node_dbus toneIndigo
```

## Components

### CLI and interface

- [CLI commands](https://github.com/simonepelosi/vibez/blob/main/cmd/root.go): `cmd/root.go`
- [Terminal UI](https://github.com/simonepelosi/vibez/blob/main/internal/tui/model.go): `internal/tui/model.go`
- [TUI panels](https://github.com/simonepelosi/vibez/tree/main/internal/tui/views): `internal/tui/views`
- [Settings](https://github.com/simonepelosi/vibez/blob/main/internal/config/config.go): `internal/config/config.go`
- [Themes and EQ](https://github.com/simonepelosi/vibez/tree/main/internal/tui): `internal/tui`

### Music sources

- [Provider interface](https://github.com/simonepelosi/vibez/blob/main/internal/provider/provider.go): `internal/provider/provider.go`
- [Apple Music](https://github.com/simonepelosi/vibez/blob/main/internal/provider/apple/apple.go): `internal/provider/apple/apple.go`
- [MusicKit auth](https://github.com/simonepelosi/vibez/tree/main/internal/auth): `internal/auth`

### Playback

- [Player interface](https://github.com/simonepelosi/vibez/blob/main/internal/player/player.go): `internal/player/player.go`
- [Chrome playback](https://github.com/simonepelosi/vibez/blob/main/internal/player/cdp/player.go): `internal/player/cdp/player.go`
- [Chrome setup](https://github.com/simonepelosi/vibez/blob/main/internal/player/cdp/browser.go): `internal/player/cdp/browser.go`
- [Preview backends](https://github.com/simonepelosi/vibez/blob/main/internal/player/webkit/player.go): `internal/player/webkit/player.go`
- [Local audio](https://github.com/simonepelosi/vibez/blob/main/internal/player/local/player_darwin.go): `internal/player/local/player_darwin.go`

### Discovery and queue

- [Queue controls](https://github.com/simonepelosi/vibez/blob/main/internal/tui/model.go): `internal/tui/model.go`
- [Vibe engine](https://github.com/simonepelosi/vibez/blob/main/internal/vibe/agent.go): `internal/vibe/agent.go`
- [Lyrics lookup](https://github.com/simonepelosi/vibez/blob/main/internal/lyrics/lrclib.go): `internal/lyrics/lrclib.go`

### System integrations

- [Last.fm client](https://github.com/simonepelosi/vibez/blob/main/internal/lastfm/client.go): `internal/lastfm/client.go`
- [MPRIS bridge](https://github.com/simonepelosi/vibez/blob/main/internal/player/mpris/server.go): `internal/player/mpris/server.go`

### Other components

- **Listener**
- **Apple Music API**
- **Chrome / Widevine**
- **Last.fm API**
- **Desktop D-Bus**

## Connections

- Listener → CLI commands: runs commands
- CLI commands → Terminal UI: starts UI
- CLI commands → MusicKit auth: manages login
- CLI commands → Settings: loads settings
- Terminal UI → Settings: reads settings
- Terminal UI → TUI panels: renders panels
- Terminal UI → Provider interface: searches and browses
- Provider interface → Apple Music: implemented by
- Apple Music → Apple Music API: requests catalog
- MusicKit auth → Apple Music API: authenticates
- Terminal UI → Player interface: controls playback
- Player interface → Chrome playback: backend
- Chrome playback → Chrome setup: prepares browser
- Chrome setup → Chrome / Widevine: launches with DRM
- Player interface → Preview backends: preview backend
- Player interface → Local audio: local-file backend
- Terminal UI → Queue controls: manages queue
- Queue controls → Provider interface: fetches candidates
- Terminal UI → Vibe engine: parses vibe input
- Terminal UI → Lyrics lookup: looks up lyrics
- Terminal UI → Last.fm client: scrobbles listening
- Last.fm client → Last.fm API: sends signed requests
- Player interface → MPRIS bridge: publishes playback state
- MPRIS bridge → Desktop D-Bus: exports controls
- Desktop D-Bus → MPRIS bridge: dispatches media actions
- Terminal UI → Themes and EQ: provides theme and EQ panels