Architecture

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

System shape

TUI / CLI / MCP / macOS / 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

Workspace responsibilities

The workspace has 18 packages: the root binary and 17 focused crates.

Package	Job
`spotuify`	unified binary entry point
`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 adapter, auth, and Web API middleware
`spotuify-provider-fake`	deterministic provider and conformance harness
`spotuify-config`	provider-neutral config loading and migration
`spotuify-player`	provider-neutral playback backends
`spotuify-sync`	background cache and provider sync
`spotuify-daemon`	server, state, sync, handlers
`spotuify-launcher`	client-side daemon lifecycle and compatibility checks
`spotuify-cli`	clap commands and output
`spotuify-tui`	ratatui client
`spotuify-mcp`	MCP tools and resources
`spotuify-system`	media controls, notifications, hooks, Discord, cover cache
`spotuify-audio`	audio visualizer and loopback capture
`spotuify-lyrics`	lyrics providers, parsing, and cache support