A device restarted with a "share" decision that another device of its group revoked meanwhile sent that card again: the first reconciler pass called sync_shares from the stale registers before device sync ran. Until DeviceSync says the registers are current (a sync exchange with a v4 device of the group after the store was attached, or no such device to wait for), passes now only unpublish cards the local registers no longer share and never call sync_shares. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
36 KiB
Furumi architecture
Furumi is an autonomous music player that can cooperate with other Furumi players. The architecture starts from one constraint: a node must remain a complete and useful player when every other node is unavailable.
Networking therefore extends a local player instead of becoming a prerequisite for it. There is no control plane, account service, canonical catalog, or server-owned source of truth.
Architectural goals
The design optimizes for five properties:
- Local autonomy — importing, browsing, playback, playlists, likes, and history work entirely on one device.
- No central failure domain — discovery, catalog exchange, streaming, and synchronization do not depend on a Furumi-operated service.
- Offline tolerance — trusted devices may change state independently and reconcile after reconnecting.
- Incremental federation — one node is complete; every additional node increases availability and the amount of discoverable music.
- Explicit trust boundaries — personal-device replication and wider music federation are different protocols with different authority.
These goals are more important than maintaining a globally identical view of the network. Furumi prefers useful local progress and eventual reconciliation over distributed consensus.
The node model
Every running Furumi instance contains the same four capabilities:
┌─────────────────────────────────────────────────────────┐
│ Furumi node │
│ │
│ Local library ── Playback engine ── TUI / media keys │
│ │ │ │
│ ├── Trusted-device replication │
│ │ │
│ └── Federation: discovery, catalog, audio │
└─────────────────────────────────────────────────────────┘
The local SQLite library is authoritative for that node. Network data is merged into local views or materialized as pending remote content; it does not replace the local database with a remote database abstraction.
This keeps the core behavior predictable:
- disconnecting never makes the local collection unavailable;
- downloaded content can become ordinary local content;
- a peer disappearing reduces availability but does not invalidate local state;
- nodes may join and leave without electing a leader.
Two network layers
Furumi deliberately separates trusted-device synchronization from federated music exchange.
Trusted-device synchronization
This layer connects devices owned or trusted by the same user. It carries personal state such as:
- likes and playlist operations;
- podcast subscriptions, episode progress and listening sessions;
- device membership and revocation;
- acknowledgements and synchronization progress;
- playback state, commands, and handoff information.
Pairing establishes the trust relationship. After that, changes are replicated
through an append-only operation log and applied to materialized local tables.
The wire types are the shared music_dht::device_sync definitions (protocol
v4); golden tests keep the v3 JSON of furumi-tui 0.3.x byte for byte.
Each device stores the protocol version that the other devices report
themselves (their hello and pairing profiles, the sender's own entry of a
devices list, their own profile announcements). A relayed profile only
raises a stored version, because older relays list every device with their
own constant; this build never stores its own version for another device.
Everything a peer cannot parse is gated by that version: podcast operations,
podcast snapshot sections and playback state that contains podcast items
reach only v4 peers (op_allowed_for_peer, SyncSnapshot::for_peer,
playback_allowed_for_peer). An older client would reject a whole message
over one unknown operation kind, or silently drop an episode it does not
understand.
Music federation
Federation connects independent libraries. It provides:
- decentralized discovery through the DHT;
- automatic publication of searchable local catalog metadata;
- richer artist and release catalogs fetched from peers;
- direct audio transfer when a selected track is not available locally.
Federation does not grant another peer authority over personal playlists, likes, or device membership. A node may participate in federation without joining another user's trusted-device group.
Keeping these layers separate prevents discovery convenience from silently becoming a synchronization trust decision.
Federation Jam control
Jam is a third, deliberately narrow authority boundary. A host creates an
opaque frid://j/... runtime capability and remains the only node producing
audio. Other TUI peers use a dedicated Jam ALPN to submit the same portable
playback commands used by connected-device control and receive the host's
playback snapshot. They receive queue metadata, not audio.
Jam never exchanges trusted membership, likes, playlists, listening history
or podcast state. The host's podcast episodes are private: the published
snapshot replaces them with opaque placeholders (redact_for_jam), guest
commands that add episodes are dropped, and a guest's placeholders are mapped
back to the host's episodes (restore_jam_private_items); a change that
drops, duplicates or seeks in them is refused. Volume remains local. Commands carry unique IDs and are retried until
the host acknowledges them, while inactive participants expire from the
runtime session. Regenerating the capability or restarting the host invalidates
the previous link.
Discovery and direct communication
Furumi separates finding content from transferring it.
discovery plane
Local catalog ───────> DHT <─────── Other catalogs
│
│ peer + content identity
v
direct P2P connection
├── catalog protocol
├── audio protocol
└── device-sync protocol
The DHT is the distributed index. Nodes publish compact searchable descriptions of their local library and query the network without contacting a central search service.
Opening a local artist or release card in a network-enabled library view enriches it asynchronously. DHT matches identify likely catalog owners, while a bounded set of known peers can also answer directly when the index is incomplete. Card results are replaceable snapshots: reopening a card or periodic maintenance retries discovery, with at most one request per card in flight. A failed refresh keeps the last usable snapshot, and never prevents browsing the local tracks.
Similarity discovery uses a separate schema-independent DHT overlay. A node derives a deterministic 256-bit routing signature from every local embedding, groups them into fixed two-level LSH buckets, and publishes compact summaries containing only fine-bucket representatives, its peer identity, and the ticket needed to dial a previously unknown owner. The owner signs every summary with its existing transport key, so storage peers can relay and cache it but cannot impersonate or modify it. Summaries expire with the ordinary library-record TTL and are replaceable federation cache, never local library authority.
A similarity search first performs bounded multi-probe LSH lookups to rank
likely owners, then sends the existing normalized-vector request directly to
at most 16 peers initially and 48 on fallback. Known peers remain a rollout
fallback. The model, preprocessing, durable embeddings, exact cosine search,
and consent policy remain client-owned; music-dht owns only compatible
routing math, signed records, replication, and wire bounds.
Once a peer is known, communication moves to direct P2P streams provided by
iroh through music-dht. Furumi defines separate application protocols for
catalog requests, audio transfer, and trusted-device synchronization. This
keeps discovery traffic small and lets large or private exchanges happen only
between the participating peers.
Relay-assisted connectivity may help peers establish a route, but relays do not become catalog authorities or application-state owners.
Identity and content resolution
Network operations refer to content independently of any one library row. Content identifiers allow a node to ask:
- Is this track already present in my local library?
- Does one of my trusted devices have it?
- Which federation peers currently advertise it?
Resolution follows that order conceptually: prefer a ready local source, reuse known content where possible, and fetch from a peer only when necessary.
A federated track can initially exist as a lightweight pending item in a queue
or playlist. When playback reaches it, Furumi resolves an available peer,
starts the transfer, and either uses the cache or imports the result into the
local library. The rest of the player continues to work with the same
TrackItem model, so local and remote availability do not require separate
playback systems.
Offline-first synchronization
Trusted devices do not share a live database connection. Each device records operations locally and exchanges them when connectivity returns.
The synchronization model combines:
- immutable operation identifiers for deduplication;
- hybrid logical timestamps for deterministic last-writer decisions;
- materialized tables for fast UI queries;
- tombstones so deletion survives offline replicas;
- per-peer acknowledgements to determine when old tombstones can be compacted;
- snapshots to repair a peer that missed older operations.
Vectors only grow, so operations hidden from a peer while it ran an older protocol are never sent again after it upgrades. Snapshots are the recovery path for that case; the podcast sections carry the subscription, share and progress registers and the most recent listening sessions, bounded by the shared FRID limits and by the line budget of each message.
This is eventual consistency scoped to a trusted device group. A temporarily offline laptop can modify playlists, another device can continue playback, and both can later converge without a permanently available coordinator.
Membership changes use the same replicated model. Revocation is state that must propagate and converge, not an ephemeral server-side session flag.
Playback across devices
A persisted device identity has exactly one live coordinator. The TUI holds an OS file lock beside its device-sync database for the entire runtime; two installations using the same user data directory cannot open it concurrently. Network polling is independent per trusted peer, with one in-flight exchange per peer and a bounded deadline. A stalled peer must not delay the next poll of a healthy output. Poll tasks are cancelled when federation shuts down.
Playback has one logical state but remains physically local to the device producing audio.
The synchronized state describes the queue, current item, position, pause
state, volume, shuffle/repeat mode, and the active playback owner. Commands are
targeted and deduplicated. Handoff transfers intent and position; the receiving
device resolves the track against its own library or federation sources before
starting its audio engine. Each queue item names its source: a podcast episode
travels as PlaybackSource::PodcastEpisode with the reference needed to play
it (the receiving device streams it from the publisher at the handed-off
position, with or without a subscription). A queue with episodes is not handed
to a device below protocol v4, and playback commands from such a device are
ignored while the local queue has episodes. Such a device still gets the
playback snapshot with its coordination envelope, but with every episode
replaced by an opaque "Private item" (redact_for_jam): an engine renews the
owner's liveness only from the owner's own announcements, so an old device
that heard nothing would take over by automatic failover after
owner_timeout_ms and replace the queue. This departs from FRID's
PLAYBACK_PROTOCOL.md rule 1 ("otherwise send None") and is reported to
FRID as a contract gap. An old device that mirrors such a queue drops the
source its types do not know, so each placeholder becomes a music item
titled "Private item"; when it later takes over (Play on it, a paused-startup
claim, failover while this device is gone) or sends a command, it announces
those. States from devices below v4 are therefore cleaned on receipt
(drop_echoed_private_items: bare music items with that title and no content
id, federated source, artist, release or duration), with a status message.
Active-device leases and idle timing prevent stale snapshots from immediately taking control after a device reconnects. This provides practical coordination without introducing a central playback arbiter.
Local application architecture
Inside one node, Furumi uses an event-driven state machine:
terminal / player / database / network / OS media events
│
v
AppEvent
│
input → Action
│
v
update(AppState)
│
optional Effect
│
v
asynchronous runtime work
│
└──────────> AppEvent
AppState is the single source of truth for the interface. The update layer
performs deterministic state transitions and requests effects; it does not
perform blocking I/O. SQLite access, imports, artwork decoding, DHT queries,
peer transfers, and audio preparation run through runtime services and report
their results as events.
This structure gives the TUI three important properties:
- rendering is a pure projection of current state;
- input behavior can be tested without starting audio or networking;
- slow peers and large imports cannot block terminal interaction.
The audio engine is similarly isolated. The application owns the logical
queue, while player::Controller owns rodio playback and receives explicit
commands. Prefetching prepares the next source before the current item ends.
Versioned key bindings
Key bindings are semantic Action values loaded from the bundled defaults and
merged with the user's keymap.toml. Some actions carry positional meaning
(GoToTab(index) follows the displayed tab order), so changing the tab order
changes what an existing user file means. The keymap file therefore carries a
format version. Files from an older format are adapted in memory when they
are loaded and the user is told once per start; Furumi never rewrites a
user's configuration. The current format, version 2, orders tabs as Library,
Playlists, Queue, Podcasts, Settings, Logs; unversioned files use the earlier
order and have their tab indices remapped. A version key that TOML attached
to a binding (written after a [[keymaps]] header) is rejected, so a versioned
file is never silently mistaken for a legacy one.
Podcasts
Podcasts are a separate content type, not library tracks. The shared contract
lives in FRID: music_dht::podcast defines podcast and episode identity, feed
URL canonicalization, the RSS/Atom parser and the merge rules, and
furumi_library::podcasts::PodcastStore persists the catalog, the personal
registers (subscription, share, progress) and listening sessions in
podcasts.sqlite3. The TUI does not re-derive ids or merge rules.
The TUI owns what the contract leaves to clients:
- Fetching. Feeds are fetched with conditional requests (ETag, Last-Modified), bounded size (32 MiB per feed, 10 MiB per cover) and time (15 s to connect, 60 s per request, 120 s for a whole fetch with its redirects), and at most 10 redirects (http and https only) followed by hand. The address that the leading permanent hops (301/308) lead to becomes a feed alias and the fetch URL, even when a temporary hop (CDN, tracker) follows it; a chain that starts with a temporary hop never moves the feed. Validators are dropped after a permanent redirect because they belong to the old address. The prototype database's validators are dropped once at import, so the first check parses the feed (seasons and episode numbers were not stored by the prototype).
- Scheduling. The store keeps each feed's local fetch state (validators,
last error, consecutive failures, next check). A timer asks it which
subscriptions are due; feeds are checked at most a few at a time, a success
waits an hour, and failures back off exponentially (honouring
Retry-After). Errors never clear the stored catalog. - Runtime boundary. Every store call, fetch and parse of the app runs on
the blocking pool or as a task and reports back through
AppEvents;update::podcastsholds the pure state transitions. The device-sync stream handlers call the store (snapshot export and merges) insideblock_in_place, so a store busy with a large feed refresh does not hold a Tokio worker's other tasks; they are never called on the UI thread. Store open failures (newer schema, foreign file) disable only the Podcasts tab and leave the file untouched. - Sync log. Local actions (subscribe, unsubscribe, mark played, progress)
draw their operation stamps from the device-sync log through
DeviceSync::run_podcast_action, and the operations are appended with exactly those stamps, so the store's registers and the log agree. The lock order is podcast store, then sync log; device sync never calls the store while it holds the log. Only the newest progress operation of an origin per episode stays in the log (later operations of one origin always win the register comparison). - Device sync. Received podcast operations are kept in the log (and
relayed) and merged into the store with
PodcastStore::apply_remote_op; invalid ones are skipped but acknowledged. Operations that arrive before the store opens wait insync_podcast_pendingand are applied when it is attached. Snapshot sections are exported withfill_snapshotand merged withapply_snapshotafter the operations of the same message. The UI reloads what it shows after such changes and checks the feed of a subscription that came from another device. - Queue identity. An episode is a
TrackItemwith an explicitpodcastreference (TrackItem::podcast_episode); its numeric id is a shared sentinel and never identifies it. Queue keys check the episode id first (ep:…), then music content ids, federated sources and library rows. Music-only paths (likes, playlists, history, content-id resolution, federation download, similarity, share links, metadata edits, release and artist jumps) checkis_podcast()and skip episodes. On the wire an episode isPlaybackSource::PodcastEpisode; received ones become episodes again (TrackItem::from_playback_track) and the library source mode never drops them. Jam private placeholders are numbered queue entries that go back on the wire asPlaybackSource::Private. - Playback. Starting an episode resolves its current audio URL and
resume position from the store, opens
podcasts::stream(a bounded Range-request reader on its own thread), decodes and positions it with coarse seeking, all off the UI and audio threads, then hands the source to the audio thread with the player's source generation. Any later start or stop bumps that generation, so a slow stream never replaces what the user chose since. A stale audio URL (4xx) triggers one feed refresh and a retry with the address the feed lists for the same episode id. A stream that cannot seek does not start at a saved position it cannot reach, and seeks in it (or in an episode still connecting) are refused. The stream is cancelled by the same generation: a superseded start stops connecting or reading up to its resume offset, and a read blocked on a stalled server inside the audio callback returns within 100 ms, so it cannot hold the audio thread past the next stop or start. The player does not report the end of a superseded source. Pause and resume pressed while a source is prepared update the intent it starts with. - End of a stream. The reader records whether the decoder stopped on a
read error (lost connection, expired URL, cancellation) and whether the
server announced the file size. Only an end that the server described, or
one within the completion window, completes the episode and moves the
queue on; otherwise the last seen position is saved and playback stops on
the episode (
playback::played_to_the_end). - Public discovery. The federation node runs FRID's signed podcast
overlay (
music_dht::podcast_dht, ALPNfurumi-fd/podcast-dht/1, cachefederation/podcast-dht.sqlite3) next to the similarity overlay: it serves the overlay, bootstraps, republishes and expires records, hands every peer capability manifest tonote_peer_capabilities, and advertisespodcast_dhtin its own manifest only while the overlay runs. A cache that cannot be opened is logged and only turns discovery off. What this device publishes is decided bypodcasts::publication: after local share and unsubscribe actions (at once:Reconciler::revoke_now), received podcast operations and feed refreshes (debounced 1 s), every overlay (re)start and every 5 minutes it builds onePodcastShareStateper subscription (merged registers, a card from the catalog for shared podcasts only, the local privacy confirmation) and calls the declarativePodcastDht::sync_shares, which publishes what is shared and tombstones every other own card. The share decision is the syncedpodcast_share_setregister, so share-off or unsubscribe on any trusted device revokes every device's card and a stale device cannot republish: untilDeviceSync::podcast_registers_currentturns true (a sync exchange applied with a v4 device of the group after the podcast store was attached, or no reachable v4 device in the group) a pass only unpublishes the own cards its registers no longer share (publication::revoke_unshared) and never callssync_shares, whose first call would re-send the cards FRID withholds from an earlier session. Publication runs from each device's own identity. Privacy confirmations of feed URLs that look private are device-local (podcast-share-confirmations.json, mode 0600) and bound to the exact URLs and to the share decision (the share register's operation): a newer decision on any device drops them. Cards leave out artwork and web links that look private, and both for a private-looking feed. Without a readable podcast store this device revokes all its own cards. The report of each pass lists the private podcasts whose own card is still live (unrevoked: pending, failed or federation off) for the side panel; the overlay peer count is refreshed every 10 s between passes. Before the node stops on quit,Reconciler::flushwaits up to 4 s for a revocation requested just before. Logs carry counts only. - Finding and subscribing.
Federation::search_podcasts(podcasts::discovery::search) runsPodcastDht::searchas its own task, bounded at 15 s including the overlay's bootstrap, apart from the music search (Federation::search, unchanged), and deliversAppEvent::FedPodcastsLoadedfor the same search sequence, so music results never wait for the overlay. The hits keep the podcast entries ofmerge_search_results(exact titles first) aspodcasts::discovery::PodcastHits. Off the UI thread each hit's origin URL is resolved withPodcastStore::resolve_podcast_id, and the "subscribed" mark compares that id and the card's id with the subscribed podcasts, so a feed alias counts. A card is a publisher's claim: onlyPodcastSearchHit::feed_url(the origin URL the id is hashed from) is ever fetched, both for the episode preview (discovery::preview, nothing stored) and for «Подписаться» (discovery::subscribe_from_hit→refresh::subscribe_url), which refuses a hit whose id does not match its URL and stores only what the feed says. Claimed moved-feed URLs are displayed, never fetched or recorded as aliases. The new subscription is private. Subscribing to an address whose feed announces (itunes:new-feed-url) a newer one this device already follows reports that subscription instead of adding a second one, and the preview (discovery::preview_for) resolves the address the feed moved to, so the card reads «Уже подписан» then. - Progress.
podcasts::progressruns one writer thread so every progress write of this device is ordered. The app tick follows the position and actual listening time and sends: an explicit start (or "start over"), checkpoints every 20 s and on pause, explicit seeks (saved once the audio thread reports that the seek worked,PlayerEvent::Seeked), completion (reaches_completionor the real end of the stream) and an end with the last seen position on stop, track change, handoff and exit. When the store reports a newer generation (another device started over, for example), the playback stops checkpointing until the user's next explicit action. Listening sessions are recorded at pause, completion and end; the store keeps those that pass the shared threshold. Queue items carry the latest progress generation this device saw, so a handoff target starts its session above it.
Scripted visualizations
Visualizations are an extension boundary rather than hard-coded rendering paths. Rust owns audio sampling, script execution, validation, and terminal drawing; Rhai scripts own the visual composition.
rodio source
│
v
audio analyzer ──> normalized features + scope samples
│
v
Rhai render(input)
│
v
validated draw commands
│
v
ratatui frame buffer
The player analyzer derives a bounded, renderer-independent input model:
energy, bass, mid, treble, beat strength, waveform samples, playback progress,
volume, pause state, track metadata, time, and terminal dimensions. Each
script implements render(input) and returns declarative commands such as
clear, cell, line, rectangle, trace, and text. Scripts never receive the
ratatui frame or audio engine directly.
This command boundary is intentional:
- scripts remain independent of Rust UI internals;
- the host validates command shapes, colors, coordinates, and arrays;
- drawing is clipped to the current terminal area;
- script failures become an in-UI visualizer error instead of corrupting the terminal or stopping playback.
Rhai files live in the user's visualization directory. The runtime discovers them dynamically, compiles the selected script, caches its AST, and recompiles it when the file modification time changes. A visualization can therefore be created or edited while Furumi is running without rebuilding or restarting the application. Bundled scripts use the same path and contract as user scripts, so built-in and custom visualizations exercise the same runtime.
The v2 primitives are sufficient for small perspective wireframes without a native 3D engine. The bundled morphing cube transforms eight vertices in Rhai and batches its twelve edges into trace/vertical-line commands. Perspective, audio-driven deformation, and depth cues stay in the user-editable script; Rust rasterizes the resulting 2D commands. This deliberately avoids per-cell script command maps and does not provide filled meshes or a depth buffer. The richer cube preset adds bounded particle, ring, inner-cage, and echo layers. Echo poses are reconstructed from earlier times with current audio features, rather than retaining previous frames; particles have deterministic lifetimes. Small terminals omit expensive layers and reduce particle counts.
The Rhai engine is configured as a sandboxed computation environment. Module
loading through import and export is disabled, no filesystem or network API
is exposed to scripts, and execution is bounded by limits on operations, call
depth, variables, functions, expression depth, and collection/string sizes.
Only the input map, Rhai language primitives, and a small set of mathematical
helpers are available.
The sandbox protects responsiveness and keeps visualization code in its intended role: transforming current audio features into drawing commands. It is not a plugin mechanism for accessing the library, network, or player controls.
Fullscreen execution currently happens synchronously during UI drawing, with a fresh Rhai scope for each frame; scripts should derive motion from time and the already-smoothed audio features rather than rely on retained mutable state. The 50 ms animation timer gives a nominal 20 FPS cadence (other events can also trigger redraws). Operation limits are not wall-clock deadlines. The host also checks the script modification time during drawing, so slow script storage or expensive custom scripts can still delay input. Benchmark script evaluation and buffer drawing separately from real terminal throughput before increasing scene complexity or the refresh rate.
The embedded status surface uses the same Rhai engine, input map, command
decoder, and clipped buffer rasterizer with a one-row viewport. It has an
independent AST cache and a fixed user-editable script in
visualizations/status/braille.rhai, installed if absent. Exact copies of the
previous bundled default can be atomically upgraded; edited files are preserved. It is not a
fullscreen preset. During local playback the visual timer samples the audio
analyzer without increasing trusted-device publication frequency. At most
one blocking render job is in flight; excess ticks are dropped. File access,
compilation, evaluation, and buffer preparation happen on that worker.
An AppEvent delivers a prepared row to AppState; UI drawing only copies
cells. Its audio input comes from the decoded-source analyzer before output
volume scaling; the volume field remains informational. Pause suspends jobs
and retains the last frame, even when the row needs resizing. Generation
checks discard results invalidated by track changes, resize, pause/resume,
or stop. Script errors are confined to the row and retried so
editing the file repairs the display. Status scripts have a smaller operation
budget, bounded source/output sizes, and cannot draw outside their viewport.
Music-similarity indexing
Similarity search is an optional local capability and is disabled by default. When enabled, a background pipeline downloads a selected ONNX model, verifies its pinned SHA-256 digest, decodes durable local tracks, and stores normalized embeddings in the library SQLite database. Embeddings are keyed by an exact fingerprint of the model artifact and preprocessing profile. Old profile rows remain available while a new profile is calculated, and the in-memory exact cosine index switches only after the replacement profile is usable.
The SQLite rows are the canonical derived store. The in-memory index can be discarded and rebuilt, and neither is required for import, browsing, or playback. Remote/cache-only tracks are never scheduled for local embedding.
Federated similarity uses a separate versioned direct-stream protocol. With explicit privacy consent, the requester sends only a normalized embedding and its profile fingerprint to a bounded set of known peers. It does not publish queries to the DHT. Each peer searches its own active local index and returns a bounded metadata result with a compact embedding SimHash. The requester uses that signature to suppress near-duplicate recordings across peers without receiving every result vector. Fan-out, concurrency, message sizes, and timeouts are bounded; incompatible profiles are rejected. This direct peer-selection layer can later be replaced by DHT routing without changing local storage or ranking.
Persistence boundaries
Furumi stores different kinds of state according to their lifetime:
| State | Storage | Role |
|---|---|---|
| Library, playlists, likes, history | SQLite | Durable local source of truth |
| Podcast subscriptions, episodes, progress | SQLite (podcasts.sqlite3, FRID store) |
Durable personal state (synced with trusted devices) and a refreshable episode catalog |
| Podcast share confirmations | JSON next to podcasts.sqlite3 |
Device-local consent to publish feed URLs that look private |
| Public podcast cards (own and replicas) | SQLite (federation/podcast-dht.sqlite3) |
Discovery overlay cache; replaceable |
| Device operation log and replicas | SQLite | Offline synchronization |
| Versioned track embeddings | SQLite | Durable, locally rebuildable similarity data |
| Federation catalog cache | SQLite/cache | Faster network browsing |
| Audio and artwork cache | Filesystem cache | Reusable fetched data |
| Settings, keymap, identity | Platform config/data dirs | Node configuration |
| Queue and playback snapshots | Application/device sync state | Continuity and handoff |
Caches are replaceable. The local library, the podcast store's personal state and the device operation log are durable. This distinction lets maintenance and recovery code discard derived network data without risking the user's collection.
Failure model
Expected failures are treated as ordinary state:
- a DHT query may return partial results;
- an advertised peer may be offline by the time a track is requested;
- a transfer may stop and be retried through another source;
- trusted devices may reconnect with overlapping changes;
- cached metadata may be stale;
- an audio device may disappear during playback.
The architecture avoids converting these cases into global failure. Search can show partial data, synchronization can resume, and playback resolution can try another source. Errors return to the application as events so the UI can expose them without terminating the node.
Main implementation boundaries
The source tree follows the architectural responsibilities:
library/owns the local catalog and import pipeline;player/owns audio playback and analysis;similarity.rsowns model acquisition, preprocessing, background indexing, and the replaceable exact in-memory index;federation/owns DHT-facing search, peer catalogs, and audio exchange;podcasts/owns feed HTTP (conditional requests, redirects, limits), refresh scheduling policy, the episode stream reader and the progress writer, the publication of shared podcasts and subscribing from public cards; the podcast model, identity, merge rules, SQLite store and discovery overlay come from FRID;devices.rsowns trusted-device replication and playback coordination;app/owns state transitions and runtime orchestration;ui/renders the TUI;media.rsintegrates platform media controls;visualizer.rshosts programmable Rhai visualizations.
Dependencies should continue to point inward toward typed models and explicit events. UI code should not own network tasks, network protocols should not mutate UI state directly, and the local library should not depend on the presence of federation.
Architectural invariants
Future changes should preserve these rules:
- A node must start and play its local library without network access.
- No central Furumi service may become required for discovery, playback, or trusted-device synchronization.
- Federation membership must not imply personal-device trust.
- Remote state must be merged or cached locally, never treated as an always available database.
- Network and storage work must remain outside the interactive UI path.
- More peers should improve availability; losing peers should only reduce remote capabilities.