Files
furumi-tui/ARCHITECTURE.md
T
2026-11-20 15:13:07 +02:00

35 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:

  1. Local autonomy — importing, browsing, playback, playlists, likes, and history work entirely on one device.
  2. No central failure domain — discovery, catalog exchange, streaming, and synchronization do not depend on a Furumi-operated service.
  3. Offline tolerance — trusted devices may change state independently and reconcile after reconnecting.
  4. Incremental federation — one node is complete; every additional node increases availability and the amount of discoverable music.
  5. 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:

  1. Is this track already present in my local library?
  2. Does one of my trusted devices have it?
  3. 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::podcasts holds the pure state transitions. The device-sync stream handlers call the store (snapshot export and merges) inside block_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 in sync_podcast_pending and are applied when it is attached. Snapshot sections are exported with fill_snapshot and merged with apply_snapshot after 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 TrackItem with an explicit podcast reference (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) check is_podcast() and skip episodes. On the wire an episode is PlaybackSource::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 as PlaybackSource::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, ALPN furumi-fd/podcast-dht/1, cache federation/podcast-dht.sqlite3) next to the similarity overlay: it serves the overlay, bootstraps, republishes and expires records, hands every peer capability manifest to note_peer_capabilities, and advertises podcast_dht in 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 by podcasts::publication: after local share and unsubscribe actions, received podcast operations, feed refreshes, every overlay (re)start and every 5 minutes it builds one PodcastShareState per subscription (merged registers, a card from the catalog for shared podcasts only, the local privacy confirmation) and calls the declarative PodcastDht::sync_shares, which publishes what is shared and tombstones every other own card. The share decision is the synced podcast_share_set register, so share-off or unsubscribe on any trusted device revokes every device's card and a stale device cannot republish. 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. Without a readable podcast store this device revokes all its own cards. Logs carry counts only.
  • Finding and subscribing. Federation::search runs PodcastDht::search next to the music DHT search and takes the podcast entries of merge_search_results (exact titles first) as podcasts::discovery::PodcastHits; the music sections keep their own aggregation and ranking, so music results are unchanged. Off the UI thread each hit's origin URL is resolved with PodcastStore::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: only PodcastSearchHit::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.
  • Progress. podcasts::progress runs 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_completion or 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.rs owns 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.rs owns trusted-device replication and playback coordination;
  • app/ owns state transitions and runtime orchestration;
  • ui/ renders the TUI;
  • media.rs integrates platform media controls;
  • visualizer.rs hosts 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:

  1. A node must start and play its local library without network access.
  2. No central Furumi service may become required for discovery, playback, or trusted-device synchronization.
  3. Federation membership must not imply personal-device trust.
  4. Remote state must be merged or cached locally, never treated as an always available database.
  5. Network and storage work must remain outside the interactive UI path.
  6. More peers should improve availability; losing peers should only reduce remote capabilities.