Architecture

spotuify is a daemon-backed runtime. The daemon is the system. The CLI, TUI, scripts, and agents are clients.

System shape

TUI / CLI / Scripts / Agents
          |
          | length-delimited JSON
          | Unix socket on Unix; named pipe on Windows
          v
       Daemon
          |
          +-- SQLite cache
          +-- Tantivy search index
          +-- Spotify Web API
          +-- Spotify Connect player

Run the surfaces:

spotuify
spotuify status --format json
spotuify daemon status

Startup state

Event-driven clients seed themselves from cached daemon state first. The TUI asks for ClientSeed, which returns playback, queue, devices, recent items, and visualizer status from the daemon/store layer without touching Spotify’s Web API. Live provider refreshes stay in daemon-owned warm/sync loops so opening the TUI does not spend rate-limit budget before the user acts.

spotuify status --format json
spotuify queue --format json
spotuify devices --format json

IPC buckets

Bucket	Examples
`core-music`	playback, devices, queue, playlists, library, search
`spotuify-platform`	cache/index state, playlist plans, saved recipes
`admin-maintenance`	status, events, logs, doctor, reset, repair, reindex
`client-specific`	pane state, selected row, modal state

Client-specific state stays out of daemon IPC.

Local truth

SQLite is the cache. Tantivy is derived and rebuildable.

spotuify cache status --format json
spotuify reindex --format json

Analytics are local SQLite too. Observed playback becomes listen_facts; historical Last.fm import stores raw rows first, then promotes high-confidence matches into the same analytics tables with import provenance.

spotuify analytics top --kind tracks --since all --format json
spotuify analytics import lastfm --user your-lastfm-user --from 2024-01-01 --format json

Copy from mxr

The docs and architecture deliberately copy mxr patterns before inventing new ones: Starlight docs, generated CLI reference, length-delimited JSON IPC, local store/search, output formats, and daemon/client separation.

spotuify search "quiet storm" --format jsonl
spotuify playlist add "Coding" spotify:track:... --dry-run

Target crate responsibilities

Crate	Job
`spotuify-core`	domain types
`spotuify-protocol`	Request, Response, Event, IPC client
`spotuify-store`	SQLite tables and queries
`spotuify-search`	Tantivy indexing and local search
`spotuify-spotify`	Spotify Web API mapping
`spotuify-player`	playback backend orchestration
`spotuify-daemon`	server, state, sync, handlers
`spotuify-cli`	clap commands and output
`spotuify-tui`	ratatui client
`spotuify-mcp`	MCP tools and resources