# aome510/spotify-player architecture

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

- Interactive diagram: https://gitdiagram.com/aome510/spotify-player
- Repository: https://github.com/aome510/spotify-player

## Overview

##### Project Type & Purpose
- This is a terminal-based music player written in Rust. It provides a feature-rich terminal interface to control Spotify playback. Its core functionalities include streaming, Spotify Connect, media control, fuzzy search, notifications, daemon support, image rendering in terminal, lyrics fetching (via the lyric_finder module), and an extensive CLI.
- The README shows that the project supports both interactive UI (with paging, popups, and keyboard shortcuts) and a CLI interface that communicates with an integrated client over a socket.

##### Analyzing the File Structure
- Two main directories stand out: “lyric_finder” and “spotify_player”. The “spotify_player” directory contains the bulk of the application including primary modules. Look at subdirectories such as:
– src/cli: Contains CLI parsing, commands, and handlers.
– src/client: Manages network requests and communication (possibly between CLI and main event loop).
– src/config: Manages configuration parsing and key-mapping settings.
– src/event, src/state, src/ui: These modules together form the interactive user interface, event handling, state management (including playback and models), and UI rendering logic.
– src/media_control, src/streaming, src/token: These handle integration with external libraries, streaming support (likely via librespot or rodio) and Spotify authentication.
- Additional files like Dockerfile, shell.nix, and CI configuration all point to automated build and deployment procedures, indicating the importance of reproducible environments.

##### Architectural Elements
a. Main Components:
- Terminal UI/Frontend: The interactive interface (using ratatui) with support for paging, popups, and shortcut handling.
- CLI Component: Processes commands (like playback start, search, authentication) and communicates with the running application via a client socket on a defined port.
- Core Application Logic: Houses the main event loop and state management including modules under src/state, src/event, src/ui.
- Spotify Integration: Covers Spotify Connect features, streaming functionalities (through librespot and selected audio backends such as rodio, alsa, pulseaudio, etc.), and media control (via MPRIS on Linux or alternative event-listeners on other OSes).
- Configuration and Caching: Modules for loading user customizations (from $HOME/.config/spotify-player) and handling cache/logging (in $HOME/.cache/spotify-player).
- Lyric Finder: A helper library/tool (lyric_finder) that provides integrated lyrics retrieval.

b. Relationships & Interactions:
- The core application logic interacts with the Spotify streaming module, which in turn depends on external libraries like librespot and various audio backends.
- The UI module receives state updates (from playback, configuration changes, and user input) and renders to the terminal; it may also call event handlers based on input.
- The configuration module is loaded at startup and influences the behavior of both UI and core logic.
- Cache and logging systems register activities from throughout the process, especially for debugging.

c. Architectural Patterns & Technology Highlights:
- Modular design: The application is divided into well-defined submodules (cli, client, config, ui, state, event) that interact primarily via defined interfaces.
- Use of external libraries/frameworks: rspotify, librespot, ratatui, and various audio libraries should be depicted as influencing the corresponding modules in streaming, media control, and UI rendering.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Subgraphs
    subgraph "Configuration and Setup"
        cfg["Configuration Manager"]:::config
    end

    subgraph "User Interfaces"
        cli["CLI Component"]:::cli
        ui["Terminal UI"]:::ui
    end

    core["Core Application Logic"]:::core

    subgraph "External Integrations"
        spotify["Spotify Integration"]:::integration
        lyrics["Lyric Finder"]:::external
    end

    %% Connections from Configuration Manager to UI components and Core
    cfg -->|"configures"| cli
    cfg -->|"configures"| ui
    cfg -->|"configures"| core

    %% Connections from User Interfaces to Core Application
    cli -->|"command"| core
    core -->|"response"| cli
    ui -->|"userEvents"| core
    core -->|"stateUpdates"| ui

    %% Core interactions with external integrations
    core -->|"streamAuth"| spotify
    core -->|"lyricsFetch"| lyrics

    %% Styling Classes
    classDef ui fill:#E3F2FD,stroke:#1976D2,stroke-width:2px;
    classDef cli fill:#C5CAE9,stroke:#303F9F,stroke-width:2px;
    classDef core fill:#B2DFDB,stroke:#00796B,stroke-width:2px;
    classDef config fill:#FFF9C4,stroke:#FBC02D,stroke-width:2px;
    classDef integration fill:#FFCDD2,stroke:#E91E63,stroke-width:2px;
    classDef external fill:#C8E6C9,stroke:#388E3C,stroke-width:2px;

    %% Click Events
    click ui "https://github.com/aome510/spotify-player/tree/master/spotify_player/src/ui"
    click cli "https://github.com/aome510/spotify-player/tree/master/spotify_player/src/cli"
    click core "https://github.com/aome510/spotify-player/blob/master/spotify_player/src/main.rs"
    click spotify "https://github.com/aome510/spotify-player/blob/master/spotify_player/src/streaming.rs"
    click cfg "https://github.com/aome510/spotify-player/tree/master/spotify_player/src/config"
    click lyrics "https://github.com/aome510/spotify-player/blob/master/lyric_finder/src/lib.rs"
```
