nordisk/knut

knut-popviz — crate card

Reverse-engineered (from source — verify, don't trust the name)

• One-line pitch: An egui desktop driver (plus a headless, robot-testable core) that generates the synthetic population as Arrow and bulk-loads it live into FalkorDB (or Iceberg), showing per-label progress.
• Does: The lib is the headless engine: run_load with LoadParams/Target (Falkor or Iceberg{warehouse}) generates the population as Arrow RecordBatches and streams them through graphar-falkordb's FalkorDbLoader, exposing a PopvizState (Phase, LabelProgress) whose state_json follows the same external-state contract the pipeline viewer uses — so the GUI is robot-testable headlessly. Generation is bounded-memory streaming: a BatchStream fans each vertex_plan/edge_plan window across all cores (gatling, LAW #0) but hands the loader one window of batches at a time (UNWIND + Iceberg lanes), so peak memory is a window, not the whole graph (the korp big-generate OOM fix); the GRAPH.BULK fast lane still buffers via gen_all_* because its encoder needs every blob at once. Streamed output is byte-identical to the buffered path (stream_matches_buffered_byte_identical). src/main.rs (feature gui) is a thin egui shell that also dumps state to $KNUT_POPVIZ_STATE for the robot test; --start-db autostarts a FalkorDB container.
• Key deps: knut-popsim (the model — re-exports LABELS/geo), graphar-falkordb (bulk load), arrow-array/arrow-schema, tokio, serde_json; feature-gated eframe/egui (0.34, gui), facett-pop (shared progress-bar components), graphar-flight (iceberg target).
• Shape: lib + knut-popviz bin (feature gui); small-medium. Modules: lib (driver/state/Arrow load), main (egui app). Has a tests/robot.rs headless GUI test.
• Observed role in the workspace: The demo front-end for population load; owns the Arrow→FalkorDB/Iceberg load path on top of the pure knut-popsim model. Shares progress components with the facett demo.

Fill in (one line each — only the human knows these)

• Primary consumer(s):
• Why it exists (vs the obvious alternative):
• Hard constraint (airgap / no-C-deps / no-FFI / pure-Rust / etc.):
• Release cadence & independence (rides a parent? own repo someday?):
• Status (production / prototype / experimental / stubbed):
• Must-NOT-change invariant:
• Biggest known gap or TODO:
• Anything a newcomer would get wrong about it: