# swadesh-c0de/vibe-fi-go architecture

> Architecture diagram of the GitHub repository swadesh-c0de/vibe-fi-go, 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/swadesh-c0de/vibe-fi-go
- Repository: https://github.com/swadesh-c0de/vibe-fi-go

## Overview

vibe-fi is a terminal music player for local files and YouTube streams. The main workflow starts in the Bubble Tea app: the user selects or searches for music, playback is controlled through the audio player, and lyrics and visualizer features enrich the playback view. Playlists, library browsing, session persistence, themes, and media integrations are distinct capabilities. The graph follows the excerpts and README; several subsystem-to-app connections are documented capabilities rather than inspected call sites.

Main entry points: [`internal/tui/app.go`](https://github.com/swadesh-c0de/vibe-fi-go/blob/main/internal/tui/app.go) (Terminal app), [`cmd/vibe/main.go`](https://github.com/swadesh-c0de/vibe-fi-go/blob/main/cmd/vibe/main.go) (CLI startup), [`internal/tui/playback_controller.go`](https://github.com/swadesh-c0de/vibe-fi-go/blob/main/internal/tui/playback_controller.go) (Playback controller), [`internal/tui/navigation_controller.go`](https://github.com/swadesh-c0de/vibe-fi-go/blob/main/internal/tui/navigation_controller.go) (Navigation controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup and UI"]
  node_main["CLI startup<br/>[main.go]"]
  node_app["Terminal app<br/>[app.go]"]
  node_navigation["Navigation controller"]
  node_playbackctl["Playback controller"]
  node_views["Terminal views"]
end

subgraph group_media["Music and playback"]
  node_mpv["MPV audio engine<br/>[mpv.go]"]
  node_search["YouTube search<br/>[search.go]"]
  node_library["Local library<br/>[library.go]"]
  node_playlist["Playlist manager<br/>[playlist.go]"]
end

subgraph group_features["Listening features"]
  node_lyrics["Synced lyrics<br/>[lyrics.go]"]
  node_visualizer["Audio visualizer<br/>[visualizer.go]"]
  node_theme["Color themes<br/>[theme.go]"]
end

subgraph group_state["State and events"]
  node_state[("Session state<br/>[state.go]")]
  node_eventbus["Playback events<br/>[eventbus.go]"]
  node_updater["Update checker<br/>[updater.go]"]
  node_bottle["yt-dlp provisioning<br/>[bottle.go]"]
end

subgraph group_integrations["System integrations"]
  node_discord["Discord presence<br/>[discord.go]"]
  node_mpris["MPRIS server<br/>[mpris.go]"]
end

node_user(("Listener"))
node_youtube["YouTube / yt-dlp"]
node_localmusic["Local music files"]
node_lrclib["lrclib.net"]
node_osmedia(("Desktop media controls"))
node_discordservice["Discord client"]

node_user -->|"operates"| node_app
node_main -->|"creates"| node_mpv
node_main -->|"creates"| node_app
node_main -->|"creates"| node_discord
node_main -->|"starts"| node_mpris
node_main -->|"checks updates"| node_updater
node_main -->|"provisions"| node_bottle
node_app -->|"routes keys"| node_navigation
node_app -->|"dispatches playback"| node_playbackctl
node_app -->|"renders"| node_views
node_app -->|"initializes"| node_library
node_app -->|"initializes"| node_playlist
node_app -->|"initializes"| node_lyrics
node_app -->|"initializes"| node_visualizer
node_app -->|"initializes"| node_eventbus
node_navigation -->|"manages playlists"| node_playlist
node_navigation -->|"starts tracks"| node_playbackctl
node_playbackctl -->|"controls playback"| node_mpv
node_playbackctl -->|"fetches lyrics"| node_lyrics
node_playbackctl -->|"publishes events"| node_eventbus
node_navigation -.->|"uses search"| node_search
node_search -->|"resolves streams"| node_youtube
node_youtube -->|"streams audio"| node_mpv
node_library -->|"browses files"| node_localmusic
node_lyrics -->|"fetches lyrics"| node_lrclib
node_lyrics -.->|"caches offline"| node_state
node_app -->|"saves session"| node_state
node_main -->|"publishes track"| node_eventbus
node_main -.->|"selects theme"| node_theme
node_mpris -->|"reads player state"| node_mpv
node_mpris -->|"sends actions"| node_app
node_osmedia -->|"controls player"| node_mpris
node_app -.->|"updates presence"| node_discord
node_discord -->|"uses IPC"| node_discordservice

click node_main "https://github.com/swadesh-c0de/vibe-fi-go/blob/main/cmd/vibe/main.go"
click node_app "https://github.com/swadesh-c0de/vibe-fi-go/blob/main/internal/tui/app.go"
click node_navigation "https://github.com/swadesh-c0de/vibe-fi-go/blob/main/internal/tui/navigation_controller.go"
click node_playbackctl "https://github.com/swadesh-c0de/vibe-fi-go/blob/main/internal/tui/playback_controller.go"
click node_views "https://github.com/swadesh-c0de/vibe-fi-go/tree/main/internal/tui/views"
click node_mpv "https://github.com/swadesh-c0de/vibe-fi-go/blob/main/internal/player/mpv.go"
click node_search "https://github.com/swadesh-c0de/vibe-fi-go/blob/main/internal/service/search/search.go"
click node_library "https://github.com/swadesh-c0de/vibe-fi-go/blob/main/internal/service/library/library.go"
click node_playlist "https://github.com/swadesh-c0de/vibe-fi-go/blob/main/internal/service/playlist/playlist.go"
click node_lyrics "https://github.com/swadesh-c0de/vibe-fi-go/blob/main/internal/service/lyrics/lyrics.go"
click node_visualizer "https://github.com/swadesh-c0de/vibe-fi-go/blob/main/internal/tui/visualizer/visualizer.go"
click node_theme "https://github.com/swadesh-c0de/vibe-fi-go/blob/main/internal/tui/theme/theme.go"
click node_state "https://github.com/swadesh-c0de/vibe-fi-go/blob/main/internal/config/state.go"
click node_eventbus "https://github.com/swadesh-c0de/vibe-fi-go/blob/main/internal/eventbus/eventbus.go"
click node_updater "https://github.com/swadesh-c0de/vibe-fi-go/blob/main/internal/service/updater/updater.go"
click node_bottle "https://github.com/swadesh-c0de/vibe-fi-go/blob/main/internal/utils/bottle/bottle.go"
click node_discord "https://github.com/swadesh-c0de/vibe-fi-go/blob/main/internal/integration/discord/discord.go"
click node_mpris "https://github.com/swadesh-c0de/vibe-fi-go/blob/main/internal/integration/mpris/mpris.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_app,node_navigation,node_playbackctl,node_views,node_discordservice toneBlue
class node_mpv,node_search,node_library,node_playlist toneAmber
class node_lyrics,node_visualizer,node_theme toneMint
class node_state,node_eventbus,node_updater,node_bottle toneRose
class node_discord,node_mpris,node_user,node_youtube,node_localmusic,node_lrclib,node_osmedia toneIndigo
```

## Components

### Startup and UI

- [CLI startup](https://github.com/swadesh-c0de/vibe-fi-go/blob/main/cmd/vibe/main.go): `cmd/vibe/main.go`
- [Terminal app](https://github.com/swadesh-c0de/vibe-fi-go/blob/main/internal/tui/app.go): `internal/tui/app.go`
- [Navigation controller](https://github.com/swadesh-c0de/vibe-fi-go/blob/main/internal/tui/navigation_controller.go): `internal/tui/navigation_controller.go`
- [Playback controller](https://github.com/swadesh-c0de/vibe-fi-go/blob/main/internal/tui/playback_controller.go): `internal/tui/playback_controller.go`
- [Terminal views](https://github.com/swadesh-c0de/vibe-fi-go/tree/main/internal/tui/views): `internal/tui/views`

### Music and playback

- [MPV audio engine](https://github.com/swadesh-c0de/vibe-fi-go/blob/main/internal/player/mpv.go): `internal/player/mpv.go`
- [YouTube search](https://github.com/swadesh-c0de/vibe-fi-go/blob/main/internal/service/search/search.go): `internal/service/search/search.go`
- [Local library](https://github.com/swadesh-c0de/vibe-fi-go/blob/main/internal/service/library/library.go): `internal/service/library/library.go`
- [Playlist manager](https://github.com/swadesh-c0de/vibe-fi-go/blob/main/internal/service/playlist/playlist.go): `internal/service/playlist/playlist.go`

### Listening features

- [Synced lyrics](https://github.com/swadesh-c0de/vibe-fi-go/blob/main/internal/service/lyrics/lyrics.go): `internal/service/lyrics/lyrics.go`
- [Audio visualizer](https://github.com/swadesh-c0de/vibe-fi-go/blob/main/internal/tui/visualizer/visualizer.go): `internal/tui/visualizer/visualizer.go`
- [Color themes](https://github.com/swadesh-c0de/vibe-fi-go/blob/main/internal/tui/theme/theme.go): `internal/tui/theme/theme.go`

### State and events

- [Session state](https://github.com/swadesh-c0de/vibe-fi-go/blob/main/internal/config/state.go): `internal/config/state.go`
- [Playback events](https://github.com/swadesh-c0de/vibe-fi-go/blob/main/internal/eventbus/eventbus.go): `internal/eventbus/eventbus.go`
- [Update checker](https://github.com/swadesh-c0de/vibe-fi-go/blob/main/internal/service/updater/updater.go): `internal/service/updater/updater.go`
- [yt-dlp provisioning](https://github.com/swadesh-c0de/vibe-fi-go/blob/main/internal/utils/bottle/bottle.go): `internal/utils/bottle/bottle.go`

### System integrations

- [Discord presence](https://github.com/swadesh-c0de/vibe-fi-go/blob/main/internal/integration/discord/discord.go): `internal/integration/discord/discord.go`
- [MPRIS server](https://github.com/swadesh-c0de/vibe-fi-go/blob/main/internal/integration/mpris/mpris.go): `internal/integration/mpris/mpris.go`

### Other components

- **Listener**
- **YouTube / yt-dlp**
- **Local music files**
- **lrclib.net**
- **Desktop media controls**
- **Discord client**

## Connections

- Listener → Terminal app: operates (evidence: `README.md`)
- CLI startup → MPV audio engine: creates (evidence: `cmd/vibe/main.go`)
- CLI startup → Terminal app: creates (evidence: `cmd/vibe/main.go`)
- CLI startup → Discord presence: creates (evidence: `cmd/vibe/main.go`)
- CLI startup → MPRIS server: starts (evidence: `cmd/vibe/main.go`)
- CLI startup → Update checker: checks updates (evidence: `cmd/vibe/main.go`)
- CLI startup → yt-dlp provisioning: provisions (evidence: `cmd/vibe/main.go`)
- Terminal app → Navigation controller: routes keys (evidence: `internal/tui/navigation_controller.go`)
- Terminal app → Playback controller: dispatches playback (evidence: `internal/tui/playback_controller.go`)
- Terminal app → Terminal views: renders (evidence: `internal/tui/app.go`)
- Terminal app → Local library: initializes (evidence: `internal/tui/app.go`)
- Terminal app → Playlist manager: initializes (evidence: `internal/tui/app.go`)
- Terminal app → Synced lyrics: initializes (evidence: `internal/tui/app.go`)
- Terminal app → Audio visualizer: initializes (evidence: `internal/tui/app.go`)
- Terminal app → Playback events: initializes (evidence: `internal/tui/app.go`)
- Navigation controller → Playlist manager: manages playlists (evidence: `internal/tui/navigation_controller.go`)
- Navigation controller → Playback controller: starts tracks (evidence: `internal/tui/navigation_controller.go`)
- Playback controller → MPV audio engine: controls playback (evidence: `internal/tui/playback_controller.go`)
- Playback controller → Synced lyrics: fetches lyrics (evidence: `internal/tui/playback_controller.go`)
- Playback controller → Playback events: publishes events (evidence: `internal/tui/playback_controller.go`)
- Navigation controller → YouTube search: uses search
- YouTube search → YouTube / yt-dlp: resolves streams (evidence: `README.md`)
- YouTube / yt-dlp → MPV audio engine: streams audio (evidence: `README.md`)
- Local library → Local music files: browses files (evidence: `README.md`)
- Synced lyrics → lrclib.net: fetches lyrics (evidence: `README.md`)
- Synced lyrics → Session state: caches offline
- Terminal app → Session state: saves session (evidence: `internal/tui/app.go`)
- CLI startup → Playback events: publishes track (evidence: `cmd/vibe/main.go`)
- CLI startup → Color themes: selects theme
- MPRIS server → MPV audio engine: reads player state (evidence: `internal/integration/mpris/mpris.go`)
- MPRIS server → Terminal app: sends actions (evidence: `internal/integration/mpris/mpris.go`)
- Desktop media controls → MPRIS server: controls player (evidence: `README.md`)
- Terminal app → Discord presence: updates presence
- Discord presence → Discord client: uses IPC (evidence: `README.md`)
