# hrkfdn/ncspot architecture

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

- Interactive diagram: https://gitdiagram.com/hrkfdn/ncspot
- Repository: https://github.com/hrkfdn/ncspot

## Overview

##### Project type and purpose
- This is a Rust‐based, terminal/console (ncurses) Spotify client (“ncspot”) that uses the librespot library to talk to Spotify’s service.
- It provides a full‐featured CLI UI, authentication, search, playback control, IPC socket, and optional MPRIS integration.

##### File structure
- Top‐level: Cargo.toml, build.rs (build script), doc/ (documentation), src/ (core application), xtask/ (custom build/dev tasks).
- src/ breaks down into:
- application.rs, main.rs, cli.rs, command(s).rs – entry point + command parsing
- config.rs, serialization.rs – config loading & data formats
- spotify_api.rs, spotify.rs, spotify_worker.rs, spotify_url.rs, authentication.rs – Spotify protocol layer + worker thread
- events.rs, ext_traits.rs, traits.rs – event bus & internal APIs
- ipc.rs, mpris.rs – external control interfaces (Unix socket + D-Bus)
- queue.rs, library.rs, sharing.rs – core playback & library logic
- model/ – domain models (Album, Artist, Track, Playlist, etc.)
- ui/ – ncurses‐based UI modules (layout, views, modals, status bar, keybindings)
- panic.rs, theme.rs, utils.rs – error handling, theming, common helpers

##### README for additional insights
- Confirms use of ncurses + librespot, premium-only features, vim keybindings, IPC socket for remote control.
- Mentions resource footprint and cross‐platform packaging.

##### Detail is key
- Iterate: start broad, then add sub‐components (e.g., list UI screens or Spotify API vs. worker).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External
    User["User (TTY)"]:::external

    %% Input Parser
    CLI["User Input & CLI Parser"]:::core
    click CLI "https://github.com/hrkfdn/ncspot/blob/main/src/cli.rs"

    %% Configuration
    Config["Configuration & Serialization"]:::integration
    click Config "https://github.com/hrkfdn/ncspot/blob/main/src/config.rs"

    %% Core Application & Event Loop
    Core["Core Application / Event Loop"]:::core
    click Core "https://github.com/hrkfdn/ncspot/blob/main/src/main.rs"

    %% Support Services
    Support["Support Services"]:::core
    click Support "https://github.com/hrkfdn/ncspot/blob/main/src/utils.rs"

    %% UI Layer
    UI["UI Layer"]:::ui
    click UI "https://github.com/hrkfdn/ncspot/tree/main/src/ui/"

    %% Domain Model
    Domain["Domain Model Layer"]:::domain
    click Domain "https://github.com/hrkfdn/ncspot/tree/main/src/model/"

    %% Spotify Integration
    Spotify["Spotify Worker & API Layer"]:::integration
    click Spotify "https://github.com/hrkfdn/ncspot/blob/main/src/spotify_api.rs"
    SpotifyService["Spotify Service"]:::external

    %% IPC and MPRIS
    IPC["IPC Socket Controller"]:::integration
    click IPC "https://github.com/hrkfdn/ncspot/blob/main/src/ipc.rs"
    MPRIS["MPRIS D-Bus Bridge"]:::integration
    click MPRIS "https://github.com/hrkfdn/ncspot/blob/main/src/mpris.rs"

    %% xtask
    xtask["xtask (Dev Tasks)"]:::external
    click xtask "https://github.com/hrkfdn/ncspot/blob/main/xtask/src/main.rs"

    %% Connections
    User -->|"input"| CLI
    CLI -->|"parse commands"| Core
    Config -->|"load settings"| Core

    Core -->|"sync update"| UI
    UI -->|"user actions"| Core
    Core -->|"update models"| Domain
    Domain -->|"state events"| Core

    Core ---|"async requests"| Spotify
    Spotify -->|"network I/O"| SpotifyService

    Core ---|"async IPC events"| IPC
    IPC -->|"commands"| Core

    Core ---|"async D-Bus events"| MPRIS
    MPRIS -->|"commands"| Core

    Core -->|"support utilities"| Support

    %% Styles
    classDef external fill:#e2e3e5,stroke:#6c757d
    classDef core fill:#d4edda,stroke:#155724
    classDef integration fill:#fff3cd,stroke:#856404
    classDef ui fill:#cce5ff,stroke:#004085
    classDef domain fill:#d4edda,stroke:#155724
```
