# haseebkhalid1507/myx architecture

> Architecture diagram of the GitHub repository haseebkhalid1507/myx, 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/haseebkhalid1507/myx
- Repository: https://github.com/haseebkhalid1507/myx

## Overview

Myx is a terminal Spotify Connect player. The principal workflow runs from user input through the app’s event/state layer to Spotify Web API browsing or librespot playback, then renders the library and playback views in the terminal. Playback events also drive album-art-reactive theming, lyrics, visualization, and optional color-protocol publishing. The README documents additional capabilities such as queue management, native media controls, and persistent equalizer settings. The graph uses the supplied tree and excerpts; unsampled subsystem wiring is shown only where documented.

Main entry points: [`src/main.rs`](https://github.com/haseebkhalid1507/myx/blob/main/src/main.rs) (Runtime loop), [`src/api/mod.rs`](https://github.com/haseebkhalid1507/myx/blob/main/src/api/mod.rs) (Web API transport), [`src/engine/mod.rs`](https://github.com/haseebkhalid1507/myx/blob/main/src/engine/mod.rs) (Connect playback), [`src/app/mod.rs`](https://github.com/haseebkhalid1507/myx/blob/main/src/app/mod.rs) (App state and actions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and state"]
  node_main["Runtime loop<br/>[main.rs]"]
  node_input["Input handlers<br/>[mod.rs]"]
  node_app["App state and actions<br/>[mod.rs]"]
  node_ui["Terminal views<br/>[mod.rs]"]
  node_persist["Saved state<br/>[persist.rs]"]
  node_config["Configuration<br/>[config.rs]"]
end

subgraph group_spotify["Spotify integration"]
  node_auth["OAuth PKCE<br/>[auth.rs]"]
  node_webapi["Web API transport<br/>[mod.rs]"]
  node_catalogue["Browse and search<br/>[library.rs]"]
  node_details["Context details<br/>[detail.rs]"]
  node_trackdata["Track and queue data<br/>[queue.rs]"]
  node_lyrics_api["Lyrics fetch<br/>[lyrics.rs]"]
  node_engine["Connect playback<br/>[mod.rs]"]
end

subgraph group_experience["Playback experience"]
  node_cache[("HTTP cache<br/>[httpcache.rs]")]
  node_theme["Reactive theme<br/>[reactive.rs]"]
  node_cover["Album artwork<br/>[cover.rs]"]
  node_lyrics["Lyrics parsing<br/>[mod.rs]"]
  node_audio["EQ and visualizer<br/>[mod.rs]"]
  node_media["OS media controls<br/>[media.rs]"]
end

subgraph group_protocol["Color protocol"]
  node_mxc["Color publisher<br/>[publish.rs]"]
  node_mxc_client["Theme CLI client<br/>[cli.rs]"]
  node_socket["Local color socket<br/>[subscribe.rs]"]
end

node_user(("User"))
node_terminal(("Terminal"))
node_spotify_service(("Spotify services"))
node_spotify(("Spotify platform"))
node_osmedia(("Operating system"))
node_subscriber(("Color subscribers"))

node_user -->|"sends input"| node_input
node_terminal -->|"provides events"| node_main
node_main -->|"dispatches events"| node_input
node_input -->|"mutates state"| node_app
node_app -->|"provides state"| node_ui
node_ui -->|"renders views"| node_terminal
node_main -->|"coordinates"| node_app
node_main -->|"restores and saves"| node_persist
node_main -->|"loads settings"| node_config
node_main -->|"gets credentials"| node_auth
node_auth -->|"authorizes with"| node_spotify_service
node_main -->|"starts API workers"| node_webapi
node_webapi -->|"serves browse requests"| node_catalogue
node_webapi -->|"serves detail requests"| node_details
node_webapi -->|"serves track requests"| node_trackdata
node_webapi -->|"serves lyric requests"| node_lyrics_api
node_catalogue -->|"fetches catalogue"| node_spotify_service
node_details -->|"fetches details"| node_spotify_service
node_trackdata -->|"fetches queue data"| node_spotify_service
node_lyrics_api -->|"fetches lyrics"| node_spotify_service
node_webapi -->|"reads and writes"| node_cache
node_webapi -->|"returns data"| node_app
node_app -->|"issues playback commands"| node_engine
node_engine -->|"streams and controls"| node_spotify
node_spotify -->|"sends player events"| node_engine
node_engine -->|"processes audio"| node_audio
node_engine -->|"emits playback events"| node_main
node_main -->|"updates on track changes"| node_theme
node_theme -->|"derives art palette"| node_cover
node_main -.->|"uses fetched lyrics"| node_lyrics
node_main -->|"handles media events"| node_media
node_media -->|"integrates controls"| node_osmedia
node_main -.->|"publishes palette"| node_mxc
node_mxc -->|"sends snapshots"| node_socket
node_mxc_client -->|"reads theme"| node_socket
node_subscriber -->|"subscribes"| node_socket

click node_main "https://github.com/haseebkhalid1507/myx/blob/main/src/main.rs"
click node_input "https://github.com/haseebkhalid1507/myx/blob/main/src/input/mod.rs"
click node_app "https://github.com/haseebkhalid1507/myx/blob/main/src/app/mod.rs"
click node_ui "https://github.com/haseebkhalid1507/myx/blob/main/src/ui/mod.rs"
click node_persist "https://github.com/haseebkhalid1507/myx/blob/main/src/app/persist.rs"
click node_config "https://github.com/haseebkhalid1507/myx/blob/main/src/config.rs"
click node_auth "https://github.com/haseebkhalid1507/myx/blob/main/src/engine/auth.rs"
click node_webapi "https://github.com/haseebkhalid1507/myx/blob/main/src/api/mod.rs"
click node_catalogue "https://github.com/haseebkhalid1507/myx/blob/main/src/api/library.rs"
click node_details "https://github.com/haseebkhalid1507/myx/blob/main/src/api/detail.rs"
click node_trackdata "https://github.com/haseebkhalid1507/myx/blob/main/src/api/queue.rs"
click node_lyrics_api "https://github.com/haseebkhalid1507/myx/blob/main/src/api/lyrics.rs"
click node_engine "https://github.com/haseebkhalid1507/myx/blob/main/src/engine/mod.rs"
click node_cache "https://github.com/haseebkhalid1507/myx/blob/main/src/httpcache.rs"
click node_theme "https://github.com/haseebkhalid1507/myx/blob/main/src/reactive.rs"
click node_cover "https://github.com/haseebkhalid1507/myx/blob/main/src/cover.rs"
click node_lyrics "https://github.com/haseebkhalid1507/myx/blob/main/src/lyrics/mod.rs"
click node_audio "https://github.com/haseebkhalid1507/myx/blob/main/src/audio/mod.rs"
click node_media "https://github.com/haseebkhalid1507/myx/blob/main/src/input/media.rs"
click node_mxc "https://github.com/haseebkhalid1507/myx/blob/main/src/mxc/publish.rs"
click node_mxc_client "https://github.com/haseebkhalid1507/myx/blob/main/src/mxc/cli.rs"
click node_socket "https://github.com/haseebkhalid1507/myx/blob/main/src/mxc/subscribe.rs"

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_input,node_app,node_ui,node_persist,node_config,node_user toneBlue
class node_auth,node_webapi,node_catalogue,node_details,node_trackdata,node_lyrics_api,node_engine toneAmber
class node_cache,node_theme,node_cover,node_lyrics,node_audio,node_media toneMint
class node_mxc,node_mxc_client,node_socket toneRose
class node_terminal,node_spotify_service,node_spotify,node_osmedia,node_subscriber toneIndigo
```

## Components

### Runtime and state

- [Runtime loop](https://github.com/haseebkhalid1507/myx/blob/main/src/main.rs): `src/main.rs`
- [Input handlers](https://github.com/haseebkhalid1507/myx/blob/main/src/input/mod.rs): `src/input/mod.rs`
- [App state and actions](https://github.com/haseebkhalid1507/myx/blob/main/src/app/mod.rs): `src/app/mod.rs`
- [Terminal views](https://github.com/haseebkhalid1507/myx/blob/main/src/ui/mod.rs): `src/ui/mod.rs`
- [Saved state](https://github.com/haseebkhalid1507/myx/blob/main/src/app/persist.rs): `src/app/persist.rs`
- [Configuration](https://github.com/haseebkhalid1507/myx/blob/main/src/config.rs): `src/config.rs`

### Spotify integration

- [OAuth PKCE](https://github.com/haseebkhalid1507/myx/blob/main/src/engine/auth.rs): `src/engine/auth.rs`
- [Web API transport](https://github.com/haseebkhalid1507/myx/blob/main/src/api/mod.rs): `src/api/mod.rs`
- [Browse and search](https://github.com/haseebkhalid1507/myx/blob/main/src/api/library.rs): `src/api/library.rs`
- [Context details](https://github.com/haseebkhalid1507/myx/blob/main/src/api/detail.rs): `src/api/detail.rs`
- [Track and queue data](https://github.com/haseebkhalid1507/myx/blob/main/src/api/queue.rs): `src/api/queue.rs`
- [Lyrics fetch](https://github.com/haseebkhalid1507/myx/blob/main/src/api/lyrics.rs): `src/api/lyrics.rs`
- [Connect playback](https://github.com/haseebkhalid1507/myx/blob/main/src/engine/mod.rs): `src/engine/mod.rs`

### Playback experience

- [HTTP cache](https://github.com/haseebkhalid1507/myx/blob/main/src/httpcache.rs): `src/httpcache.rs`
- [Reactive theme](https://github.com/haseebkhalid1507/myx/blob/main/src/reactive.rs): `src/reactive.rs`
- [Album artwork](https://github.com/haseebkhalid1507/myx/blob/main/src/cover.rs): `src/cover.rs`
- [Lyrics parsing](https://github.com/haseebkhalid1507/myx/blob/main/src/lyrics/mod.rs): `src/lyrics/mod.rs`
- [EQ and visualizer](https://github.com/haseebkhalid1507/myx/blob/main/src/audio/mod.rs): `src/audio/mod.rs`
- [OS media controls](https://github.com/haseebkhalid1507/myx/blob/main/src/input/media.rs): `src/input/media.rs`

### Color protocol

- [Color publisher](https://github.com/haseebkhalid1507/myx/blob/main/src/mxc/publish.rs): `src/mxc/publish.rs`
- [Theme CLI client](https://github.com/haseebkhalid1507/myx/blob/main/src/mxc/cli.rs): `src/mxc/cli.rs`
- [Local color socket](https://github.com/haseebkhalid1507/myx/blob/main/src/mxc/subscribe.rs): `src/mxc/subscribe.rs`

### Other components

- **User**
- **Terminal**
- **Spotify services**
- **Spotify platform**
- **Operating system**
- **Color subscribers**

## Connections

- User → Input handlers: sends input
- Terminal → Runtime loop: provides events
- Runtime loop → Input handlers: dispatches events
- Input handlers → App state and actions: mutates state
- App state and actions → Terminal views: provides state
- Terminal views → Terminal: renders views
- Runtime loop → App state and actions: coordinates
- Runtime loop → Saved state: restores and saves
- Runtime loop → Configuration: loads settings
- Runtime loop → OAuth PKCE: gets credentials
- OAuth PKCE → Spotify services: authorizes with
- Runtime loop → Web API transport: starts API workers
- Web API transport → Browse and search: serves browse requests
- Web API transport → Context details: serves detail requests
- Web API transport → Track and queue data: serves track requests
- Web API transport → Lyrics fetch: serves lyric requests
- Browse and search → Spotify services: fetches catalogue
- Context details → Spotify services: fetches details
- Track and queue data → Spotify services: fetches queue data
- Lyrics fetch → Spotify services: fetches lyrics
- Web API transport → HTTP cache: reads and writes
- Web API transport → App state and actions: returns data
- App state and actions → Connect playback: issues playback commands
- Connect playback → Spotify platform: streams and controls
- Spotify platform → Connect playback: sends player events
- Connect playback → EQ and visualizer: processes audio
- Connect playback → Runtime loop: emits playback events
- Runtime loop → Reactive theme: updates on track changes
- Reactive theme → Album artwork: derives art palette
- Runtime loop → Lyrics parsing: uses fetched lyrics
- Runtime loop → OS media controls: handles media events
- OS media controls → Operating system: integrates controls
- Runtime loop → Color publisher: publishes palette
- Color publisher → Local color socket: sends snapshots
- Theme CLI client → Local color socket: reads theme
- Color subscribers → Local color socket: subscribes