flutter-rust-bridge

name	flutter-rust-bridge
description	Domain knowledge, architecture guidelines, and constraints for the beadline cross-platform media application.
compatibility	opencode

What I do

• Guide development for the beadline multi-platform media application.
• Enforce the separation of concerns between core media/systems workloads and the user interface.
• Prevent regressions in the code generation pipeline and binary updating strategies.

Platform Strategy: All-in-Rust, Flutter as a UI Shell

• Long-term target: Dioxus. The desired end-state is to eliminate FFI entirely and render with a Rust-native UI framework (Dioxus, rsx, desktop + mobile). Once Dioxus reaches production maturity for our targets, the Flutter layer will be dropped and the UI will run inside the Rust process.
• Why Flutter is still here: Dioxus is not yet mature enough (tooling, mobile ecosystem, plugins) for this application today. Flutter is the pragmatic, current UI.
• The core rule — "Flutter UI only, all in Rust for logic":
  1. EVERY piece of state management, media pipeline, domain/business logic, networking, and parsing lives in vanilla Rust crates under crates/. Zero logic in Dart.
  2. The Dart layer (/lib) is a thin rendering shell: widgets, gesture-to-command translation (calling FRB methods), and minimal view-state derived from Rust-driven streams/snapshots. No domain model, no business decisions, no file/network I/O in Dart.
  3. If a decision or computation is needed by the UI, implement it in Rust first and expose it over the bridge; do not reimplement it in Dart "temporarily".
  4. Rust crates must remain Flutter-agnostic and Dioxus-agnostic: they expose plain types (serde-able snapshots/commands/events), never Flutter-specific or FRB-generated concepts. FRB mirrors of those types live only in crates/ffi_beadline.
• Migration-readiness checklist (every feature must satisfy these):
  • The feature is fully implementable and unit-testable from pure Rust (cargo test), with no Flutter/FFI dependency.
  • Dart consumes it as dumb snapshots + one-way commands (stream via StreamSink, commands via FRB methods). No bidirectional object graphs across the bridge.
  • Any async/stream behaviour is owned by Rust (tokio tasks); Dart only subscribes.
  • Nothing depends on Dart-only capabilities (e.g., a StreamController in Dart that Rust cannot mirror) in a way that would need to be rewritten for Dioxus.

Workspace Architecture Layout

• Frontend Layer (/lib): Pure UI layer written in Dart. Contains only user interaction code and the generated FRB Dart outputs. Must remain thin — see the Platform Strategy above.
• FFI Bridge Crate (/crates/ffi_beadline): The Rust workspace wrapper that exposes API structures to the Flutter bridge. Thin adapters only; no business logic that belongs in core crates.
• Core Crates (/crates/beadline_*): Vanilla Rust. Contain high-resolution audio processing, state machines, cast transport (Chromecast), local media serving, and custom lyric parsing logic. Completely decoupled from Flutter — and from Dioxus, so the same code runs under either UI.

Strict Operational Constraints

1. FFI Location: All raw FFI logic and entry points must sit inside crates/ffi_beadline_bridge/src/api. Add rust struct by modifying rust_input in flutter_rust_bridge.yaml. Do not implement native FFI boilerplate outside this crate space.
2. Bridge Isolation: Never manually edit frb_generated.rs or lib/src/rust/**. If any changes are made to the exposed Rust signatures, immediately run the codegen macro command.
3. Atomic Side-by-Side Updates: When handling binary installation, updates, or patching for Windows and Linux targets, adhere tightly to the symlink-driven atomic delta update pattern. Do not write inplace binary overwrites.
4. Localization: When updating translation configurations or asset files, trigger the custom slang macro command to synchronize the localization keys.

State-Truth Principle (room sync & persistence)

• In-memory Rust state is the runtime truth. The Rust server (beadline-sharing) owns the authoritative room state: queue, catalog, playback snapshot, settings, permissions, participants, access code. Host Dart pushes deltas into it (update_server_queue_json etc.); it never "recomputes" what the server holds.
• Plain files are restart restore only. room.json / access_code.json next to the persist dir are snapshots written when state changes; they are loaded at startup, never queried at runtime, never treated as a live store.
• SQLite is an optimization only. If a DB exists it mirrors Rust-owned state for fast queries; the Rust in-memory state remains the source of truth and the DB must be rebuildable from it.
• Guests pull on join: the server answers CatalogRequest / QueueRequest from its stored snapshots; the host does not re-push on join.
• Guest playback uses the Rust playback clock: events (playback_clock_update) + a 1s local display timer (prediction), corrected on the 10s host truth tick (playback_clock_corrected_position_ms). Guests never poll the host.
• Wire messages are thin commands/snapshots (serde JSON over WebSocket); all validation, permission gating, and drift math happen in Rust. See crates/beadline-sharing/src/{access_code,permissions,playback_clock}.rs.