The Rust, WASM, and
Flutter stack

The Simulation Core: Rust and a Discrete Event Scheduler

The heart of the system is a discrete event simulation (DES) engine written in pure Rust. No async runtime. No threads (WASM is single-threaded in browsers). Just a priority queue of timestamped events and a tight loop that processes them.

pub struct Simulator {
    event_queue: BinaryHeap<Reverse<SimEvent>>,
    clock: SimTime,
    nodes: HashMap<NodeId, Node>,
    network: NetworkTopology,
}

impl Simulator {
    pub fn step(&mut self) -> Option<SimEvent> {
        let event = self.event_queue.pop()?.0;
        self.clock = event.time;
        self.dispatch(event.clone());
        Some(event)
    }
}

SimTime is a u64 representing nanoseconds of simulated time — not wall time. The simulation can run a full 60-second scenario in 200 milliseconds of real time, or deliberately slow down to let you watch a Raft leader election happen in human-perceivable steps.

The BinaryHeap<Reverse<SimEvent>> pattern is the standard DES trick — Reverse flips the max-heap into a min-heap so the earliest event always pops first. Events carry a type, a target node ID, a payload, and a timestamp.

Determinism as a Feature

Every random value in the simulator comes from a seeded PRNG — specifically SmallRng from the rand crate, seeded at scenario start. Network latency jitter, packet loss events, node failure timing — all seeded.

This means a scenario is fully replayable. You can serialize the seed and the event log, send it to a colleague, and they run the exact same simulation. The "share scenario" feature works exactly this way: it's a seed and a config JSON, not a recording of every event.

It also means the test suite can run the simulator and assert on specific event sequences. If a Raft implementation regresses, the test fails deterministically — not flakily.

Compiling to WASM: The wasm-bindgen Bridge

The Rust core compiles to a .wasm binary via wasm-pack. The interface surface exposed to the outside world is defined with #[wasm_bindgen] macros:

#[wasm_bindgen]
pub struct SimulatorHandle {
    inner: Rc<RefCell<Simulator>>,
}

#[wasm_bindgen]
impl SimulatorHandle {
    #[wasm_bindgen(constructor)]
    pub fn new(config_json: &str) -> Result<SimulatorHandle, JsValue> {
        let config: ScenarioConfig = serde_json::from_str(config_json)
            .map_err(|e| JsValue::from_str(&e.to_string()))?;
        Ok(SimulatorHandle {
            inner: Rc::new(RefCell::new(Simulator::from_config(config))),
        })
    }

    pub fn step(&mut self) -> JsValue {
        match self.inner.borrow_mut().step() {
            Some(event) => serde_wasm_bindgen::to_value(&event).unwrap(),
            None => JsValue::NULL,
        }
    }
}

The Rc<RefCell<>> wrapping is necessary because wasm_bindgen doesn't support mutable references across the FFI boundary in the way you'd want. You wrap in RefCell and take the borrow at call time. It's not pretty. It's the standard pattern.

Serialization crosses the boundary as JSON strings (for config) or via serde_wasm_bindgen (for event data). The latter avoids an intermediate JSON parse/stringify round-trip for the hot path — the step() call that fires potentially thousands of times per second.

The Flutter Shell: Why Not Just a Web App?

The question that comes up every time: why Flutter? The honest answer: the node graph canvas. Rendering 500+ nodes with animated edges, real-time packet-in-flight visualization, and smooth 60fps interaction is genuinely difficult in the browser DOM. SVG doesn't scale. Canvas 2D requires careful manual dirty-region tracking. WebGL is correct but means writing a mini rendering engine.

Flutter's CustomPainter with Canvas gives a retained-mode drawing API backed by Skia (or Impeller on newer targets). The node graph renderer is a single CustomPainter subclass:

class SimulatorBridge {
  late js.JSObject _handle;

  Future<void> initialize(ScenarioConfig config) async {
    final configJson = jsonEncode(config.toJson());
    _handle = SimulatorWasm.create(configJson.toJS);
  }

  SimEvent? step() {
    final result = _handle.callMethod('step'.toJS);
    if (result.isNull) return null;
    return SimEvent.fromJson(result.dartify() as Map);
  }
}

This is deliberately thin. The bridge does type conversion and nothing else. Business logic stays in Rust. Rendering logic stays in Flutter. The bridge is not the place for either.

The node graph renderer transforms world coordinates to screen coordinates using a Matrix4 maintained by the pan/zoom gesture handler, draws edges first (z-order), then nodes, then in-flight packet animations — and only repaints when the simulation emits a new event or the user interacts.

The Render Loop

Flutter's animation system drives the simulation step rate. A Ticker fires every frame (targeting 60fps). Each tick, the Flutter layer calls step() on the Rust core some number of times — controlled by a "simulation speed" multiplier.

Events returned by step() flow into a stream that the UI layer subscribes to. State changes — node status, message queues, leader election outcomes — are applied to Flutter ChangeNotifier objects. Widgets rebuild only when their specific state changes. Even at 100× speed, the Dart side isn't doing work proportional to the number of simulation events — it's batching state deltas and applying them once per frame.

What This Architecture Gets You

Specific dependencies worth naming

• wasm-bindgen 0.2.x The FFI glue. Macro expansion is verbose but the output is correct.
• serde + serde_wasm_bindgen Serialization across the boundary. serde_wasm_bindgen avoids the JSON string intermediary for hot-path calls.
• rand (SmallRng) Fast, seedable, portable PRNG. Not cryptographic, which is fine here.
• wasm-pack Build toolchain that handles wasm-opt post-processing and generates the JS/TS glue code.
• priority-queue Used where event priorities need to change (Dijkstra-style). The standard BinaryHeap doesn't support priority updates.
• flutter_riverpod State management on the Flutter side — ChangeNotifier providers per feature slice.