IFM

Appearance

IFM Architectural Invariants ​

This document specifies the non-negotiable architectural rules and boundaries of the IFM Protocol system. These invariants MUST remain true regardless of refactoring, feature development, or optimization.

Invariant 1: Protocol Single Source of Truth ​

  • Definition: crates/protocol is the single authoritative source of truth for binary wire packets, frame structures, payload types, and header layouts.
  • Rule: No package (including @ifm/sdk, Tauri apps, or PWA) may define duplicate or conflicting packet wire schemas.
  • Rationale: Prevents wire protocol fragmentation and serialization mismatches between clients written in different languages.
  • Definition: crates/audio provides pure audio codec machinery (Opus encoding/decoding, adaptive jitter buffering — 10ms real-time default, 5/20ms runtime-selectable — energy VAD, PLC).
  • Rule: crates/audio depends ONLY on ifm-protocol (EncodedAudioFrame). It MUST NEVER depend on ifm-transport, libp2p, or network sockets. Capture/playback device I/O (cpal, Web Audio) belongs exclusively in application layers.
  • Modular Pipeline Rule: Audio production, mixing, processing (DSP), codec, recording, transport, and discovery are strictly independent, replaceable components (Sources → Mixer (optional) → Processing → Codec → Audio Frames → (Transport + Record)).
  • Mixer Independence: The mixer is optional and replaceable. The mixer MUST NOT contain networking, transport, relay, rendezvous, or recording logic.
  • Rationale: Guarantees audio codec logic is 100% testable in memory, cross-platform portable (WASM, embedded, native), and decoupled from network transport behavior.

Invariant 3: Transport Agnosticism ​

  • Definition: crates/transport provides a unified transport abstraction over QUIC, WebRTC, TCP, and InMemoryMesh.
  • Rule: The core protocol engine (ifm-core) interacts with transport solely via abstract frames and topics. Transport layers MUST NEVER inspect Opus payload samples or execute audio processing.
  • Rationale: Enables swapping or adding new transport mechanisms (e.g. WebTransport, Bluetooth LE mesh) without touching protocol or audio logic.

Invariant 4: Relay Neutrality & Passive Forwarding ​

  • Definition: Relays forward packets across the mesh using public header data (Topic ID, TTL, Ed25519 signature, BLAKE3 packet ID).
  • Rule: Relays DO NOT decrypt protected frequency payloads and DO NOT inspect or alter audio payload bytes. Relays are station-agnostic and frequency-agnostic infrastructure.
  • Rationale: Preserves privacy, end-to-end encryption guarantees, and ensures zero-trust relay infrastructure.

Invariant 5: Headless Core Isolation ​

  • Definition: crates/core is a pure headless protocol node orchestrator (Node::new(), tune(), broadcast()).
  • Rule: Core logic MUST NOT contain UI dependencies, terminal UI code, or platform-specific web assumptions.
  • Rationale: Allows the same Rust core to power CLI binaries, desktop apps, servers, background daemons, and WASM web builds.

Invariant 6: Non-Blocking Live Audio Transport ​

  • Definition: Real-time media frames (10ms Opus by default, spec docs/features/realtime-media-transport.md) travel on the unreliable datagram channel (Transport::send_media/broadcast_media/on_media) with per-stream sequence + timestamp, audio-clock playback, adaptive jitter buffering, and live-edge tracking. Media is a real-time channel distinct from the reliable channel (chat/files/control).
  • Rule: Heavy payload transfers (file transfers, chat history replays, metadata sync) MUST NOT block or introduce jitter into live audio transport.
  • Rationale: Protects real-time voice quality under heavy network load.

Invariant 7: Decoupled Rendezvous Discovery Node ​

  • Definition: crates/rendezvous is a standalone, headless discovery and signaling service node.
  • Rule: Rendezvous nodes MUST NOT depend on station UI components, audio mixing pipelines, or application frontend states.
  • Rationale: Allows deploying ultra-lightweight discovery nodes on cloud servers, edge infrastructure, or micro-vms.

Invariant 8: Independent & Non-Blocking Recording Component ​

  • Definition: Recording is an independent audio component that consumes either processed PCM audio or EncodedAudioFrame streams.
  • Rule: Recording MUST NOT leak concerns into the mixer, processor, codec, or transport. Recording MUST be independently buffered and non-blocking so that slow disks, storage errors, or file writers NEVER stall live audio broadcast transport.
  • Rationale: Guarantees that stations can broadcast only, record only, or broadcast and record simultaneously without latency or reliability degradation.

Invariant 9: SDK Examples Follow the Desktop Apps — ALWAYS, Never the Contrary ​

  • Definition: The SDK web demos (packages/sdk/examples/*) are followers of the desktop implementations (packages/ifm-*), never the other way around.
  • Rule: Shared UI code (e.g. the broadcast console at packages/ifm-station/src/mixer/) is authored in the DESKTOP app and synced INTO the example. The desktop app is the source of truth; the demo mirrors it and never diverges. Never edit a shared desktop file to match an example, and never treat an SDK example as canonical for shared code.
  • Rule: When a shared file changes, apply the change in the desktop app first, then copy it to the example (the sync direction is always desktop → example, never example → desktop).
  • Rationale: The desktop apps are the product surface where new capabilities land (native audio, Tauri seams, OS integration); the SDK examples demonstrate the same surface in the browser. Making the examples the source of truth would let browser-only limitations leak backward into the desktop apps and silently degrade the product.

Invariant 10: Independent Transport Lines ​

  • Definition: IFM MUST keep different traffic classes on independent transport lines. A transport line is dedicated to a specific traffic purpose and MUST NOT be used as a general-purpose container for unrelated traffic.

  • Traffic classes: At minimum, IFM treats these as independent lines: AUDIO (voice), VIDEO, CHAT (text messages), TELEMETRY, FILE, and CONTROL (discovery/station records, relay announcements). Additional classes may be introduced without changing the architecture.

  • Rule: Different traffic classes MUST remain independently transportable and MUST NOT be coupled into one application-level stream merely for convenience. A failure, congestion, or high-volume transfer on one line MUST NOT block or significantly degrade unrelated real-time lines (a large file transfer must not interfere with a live audio stream).

  • Rule: Traffic lanes are identified by payload type: voice/video are real-time lanes (low latency, loss tolerance, jitter management, continuous delivery), chat/file/telemetry/data are reliable lanes (ordering, integrity, retransmission, throughput). Each lane may have its own encoding, packet handling, queue, buffering, priority, reliability requirements, congestion behavior, and transport implementation.

  • Logical isolation, not necessarily physical sockets: "Independent lines" does not require a physically separate network connection per lane. The implementation MAY share lower-level network infrastructure while maintaining separate logical transport channels, queues, priorities, flow control, and failure domains. The architectural requirement is logical isolation: the mesh remains shared, the traffic lanes remain independent.

  • Implementation: The frequency payload plane is split into per-lane GossipSub topics (/ifm/{topic_id}/{voice|video|chat|file|data}) on every transport; the browser-overlay WebRTC connection gives each lane its own data channel with its own reliability semantics (voice/video unordered + loss-tolerant, chat/file/data ordered + reliable). The control plane already has dedicated topics (/ifm/stations/v1, /ifm/relays/v1, /ifm/telemetry/v1).

  • Rationale: Real-time traffic has different requirements than reliable traffic. Putting all classes into one busy application stream allows one class to interfere with another (e.g. a file transfer blocking live audio). Keeping the lanes logically independent protects real-time quality while leaving room to map lanes intelligently onto QUIC streams, WebRTC data channels, TCP connections, etc. without coupling the application protocols together.

Invariant 11: Station-Owned Content State & Local Client Conversion ​

  • Definition: Stations own their source and content state. The protocol transports the station's real-time stream and associated data, while listeners perform all media decoding and conversion locally.
  • Rule: Stations MUST NOT pre-convert audio into listener-specific formats or perform expensive per-listener transcoding. Listeners MUST consume the stream continuously and handle required conversion locally.
  • Rationale: Radio is inherently real-time where latency matters more than eventual consistency. Prioritizing fast path establishment and continuous low-latency delivery over file transfer or centralized processing ensures true real-time performance and architectural scaling.

Released under the MIT License.

Copyright © 2026 IFM Protocol Contributors