# raitonoberu/sptlrx architecture

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

- Interactive diagram: https://gitdiagram.com/raitonoberu/sptlrx
- Repository: https://github.com/raitonoberu/sptlrx

## Overview

##### Project type and purpose
- It’s a cross-platform, single-binary CLI application written in Go.
- Purpose: fetch and display synchronized lyrics in the terminal or pipe them to stdout, supporting multiple “players” (Spotify, MPD, Mopidy, MPRIS, browser) and local files.

##### File structure
Top-level directories and files:
- cmd/             – CLI entrypoints (root command, “pipe” subcommand)
- config/          – configuration loader and structs
- services/        – player adapters (spotify, mpd, mopidy, mpris, browser, local, hosted)
- pool/            – lyric caching & synchronization logic
- lyrics/          – parsing .lrc files and calling external lyrics API
- player/          – generic player interface & helpers
- ui/              – terminal rendering logic
- main.go          – application bootstrap
- building files   – goreleaser, CI workflows, man pages

##### README for additional insights
- Describes supported players, configuration file, external dependencies (Spotify web, custom lyrics API, local .lrc).
- Mentions “pipe” mode for stdout integration.

##### Main components
1. CLI Layer
– cmd/root.go, cmd/pipe.go
– Parses flags, reads config, dispatches to either interactive UI or pipe mode
2. Config Manager
– config/config.go
– Loads config.yaml, merges flags and defaults
3. Player Adapters (“services” package)
– Each subpackage implements a common interface (GetTrackInfo, Position, etc.)
– Spotify: uses web cookie + Spotify web API
– MPD/Mopidy: TCP connections to music servers
– MPRIS: D-Bus on Linux
– Browser: HTTP server communicating with browser extension
– Local: scans folder for .lrc files
– Hosted: falls back to external lyrics API
4. Lyrics Fetcher
– lyrics/lyrics.go
– Given track metadata, fetches parsed lyrics (from local .lrc or HTTP)
5. Pool & Synchronizer
– pool/pool.go
– Caches parsed lyrics, manages timing (timerInterval, updateInterval)
– pool_test.go ensures timing logic
6. UI Renderer
– ui/ui.go
7. Pipe Mode
– Directly prints current line(s) to stdout for integration
8. External Systems
– Spotify web API
– Lyrics API server (lyricsapi.vercel.app or self-hosted)
– MPD/Mopidy servers
– D-Bus for MPRIS
– Browser extension HTTP endpoint
– Local file system for .lrc files

##### Relationships and data flow
- User invokes “sptlrx” or “sptlrx pipe”
- CLI layer reads flags → loads config
- Config determines which service adapter to initialize
- Service adapter polls the player for current track & position
- Lyrics Fetcher retrieves lyrics (via adapter to local/HTTP)
- Pool synchronizes lyrics lines to playback time
- UI Renderer subscribes to pool updates → draws to terminal
- In pipe mode, UI Renderer replaced by Pipe Writer (stdout)

##### Important architectural patterns
- Adapter/plugin pattern for player support (each service implements the same interface)
- Layered architecture: CLI → config → service → domain (lyrics+pools) → presentation (ui or pipe)
- Dependency injection via constructors in cmd/root.go
- Single binary distribution with Go modules and goreleaser

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Application Bootstrap"
        MAIN["Bootstrap\n(main.go)"]:::internal
    end

    subgraph "CLI Layer"
        ROOT["Root Command\n(cmd/root.go)"]:::internal
        PIPECMD["Pipe Command\n(cmd/pipe.go)"]:::internal
    end

    subgraph "Config Manager"
        CONFIG["Config Manager\n(config/config.go)"]:::internal
    end

    subgraph "Player Adapters"
        SPOT["Spotify Adapter\n(services/spotify/spotify.go)"]:::adapter
        MPD["MPD Adapter\n(services/mpd/mpd.go)"]:::adapter
        MOP["Mopidy Adapter\n(services/mopidy/mopidy.go)"]:::adapter
        MPR_UNIX["MPRIS Unix Adapter\n(services/mpris/mpris_unix.go)"]:::adapter
        MPR_UNSUP["MPRIS Unsupported Adapter\n(services/mpris/mpris_unsupported.go)"]:::adapter
        BROW["Browser Adapter\n(services/browser/browser.go)"]:::adapter
        LOC["Local Adapter\n(services/local/local.go)"]:::adapter
        HOST["Hosted Adapter\n(services/hosted/hosted.go)"]:::adapter
    end

    subgraph "Lyrics Fetcher"
        LF["Lyrics Fetcher\n(lyrics/lyrics.go)"]:::internal
    end

    subgraph "Pool & Synchronizer"
        POOL["Pool & Synchronizer\n(pool/pool.go)"]:::internal
        POOL_TEST["Pool Tests\n(pool/pool_test.go)"]:::internal
    end

    subgraph "Presentation"
        UIR["UI Renderer\n(ui/ui.go)"]:::internal
        PIPE["Pipe Writer\n(cmd/pipe.go)"]:::internal
    end

    subgraph "External Systems"
        SPOTAPI["Spotify Web API"]:::external
        LYRICAPI["Lyrics API Server"]:::external
        MPDSRV["MPD/Mopidy Server"]:::external
        DBUS["D-Bus (MPRIS)"]:::external
        BROWSEREXT["Browser Extension HTTP"]:::external
        FS["File System (.lrc)"]:::external
    end

    MAIN --> ROOT
    MAIN --> PIPECMD

    ROOT --> CONFIG
    PIPECMD --> CONFIG

    CONFIG --> SPOT
    CONFIG --> MPD
    CONFIG --> MOP
    CONFIG --> MPR_UNIX
    CONFIG --> MPR_UNSUP
    CONFIG --> BROW
    CONFIG --> LOC
    CONFIG --> HOST

    SPOT --> SPOTAPI
    MPD --> MPDSRV
    MOP --> MPDSRV
    MPR_UNIX --> DBUS
    MPR_UNSUP --> DBUS
    BROW --> BROWSEREXT
    LOC --> FS
    HOST --> LYRICAPI

    SPOT -->|"track info & position"| LF
    MPD -->|"track info & position"| LF
    MOP -->|"track info & position"| LF
    MPR_UNIX -->|"track info & position"| LF
    MPR_UNSUP -->|"track info & position"| LF
    BROW -->|"track info & position"| LF
    LOC -->|"track info & position"| LF
    HOST -->|"track info & position"| LF

    LF -->|"lyrics lines"| POOL
    POOL --> POOL_TEST

    POOL -->|"synchronized lines"| UIR
    POOL -->|"current line"| PIPE

    classDef internal fill:#d5f5e3,stroke:#27ae60,stroke-width:1px
    classDef adapter fill:#aed6f1,stroke:#2980b9,stroke-width:1px
    classDef external fill:#f9e79f,stroke:#d68910,stroke-width:1px

    click ROOT "https://github.com/raitonoberu/sptlrx/blob/master/cmd/root.go"
    click PIPECMD "https://github.com/raitonoberu/sptlrx/blob/master/cmd/pipe.go"
    click CONFIG "https://github.com/raitonoberu/sptlrx/blob/master/config/config.go"
    click SPOT "https://github.com/raitonoberu/sptlrx/blob/master/services/spotify/spotify.go"
    click MPD "https://github.com/raitonoberu/sptlrx/blob/master/services/mpd/mpd.go"
    click MOP "https://github.com/raitonoberu/sptlrx/blob/master/services/mopidy/mopidy.go"
    click MPR_UNIX "https://github.com/raitonoberu/sptlrx/blob/master/services/mpris/mpris_unix.go"
    click MPR_UNSUP "https://github.com/raitonoberu/sptlrx/blob/master/services/mpris/mpris_unsupported.go"
    click BROW "https://github.com/raitonoberu/sptlrx/blob/master/services/browser/browser.go"
    click LOC "https://github.com/raitonoberu/sptlrx/blob/master/services/local/local.go"
    click HOST "https://github.com/raitonoberu/sptlrx/blob/master/services/hosted/hosted.go"
    click LF "https://github.com/raitonoberu/sptlrx/blob/master/lyrics/lyrics.go"
    click POOL "https://github.com/raitonoberu/sptlrx/blob/master/pool/pool.go"
    click POOL_TEST "https://github.com/raitonoberu/sptlrx/blob/master/pool/pool_test.go"
    click UIR "https://github.com/raitonoberu/sptlrx/blob/master/ui/ui.go"
    click PIPE "https://github.com/raitonoberu/sptlrx/blob/master/cmd/pipe.go"
    click MAIN "https://github.com/raitonoberu/sptlrx/blob/master/main.go"
```
