# RVF Model Container Architecture in RuView: Progressive Loading Explained

> Discover the RVF model container architecture in RuView. Learn how progressive loading streams heavy weights for instant UI feedback and efficient Wi-Fi DensePose deployment.

- Repository: [rUv/RuView](https://github.com/ruvnet/RuView)
- Tags: architecture
- Published: 2026-03-08

---

**The RVF (RuView File) format bundles Wi-Fi DensePose model components into a single 64-byte-aligned container with a three-layer progressive loader that delivers instant UI feedback while streaming heavy weights in the background.**

The RuView project implements a specialized container format called RVF (RuView File) to package trained Wi-Fi DensePose models for deployment. Understanding the RVF model container architecture is essential for optimizing inference startup times and managing large model artifacts. This article examines how the container structure organizes model weights, metadata, and indices, and details the progressive loading mechanism that enables sub-millisecond initialization.

## What is the RVF Model Container?

The RVF format is a single-file container that bundles everything a Wi-Fi DensePose model needs for inference. Unlike standard ONNX or PyTorch checkpoints, RVF segments are self-describing and 64-byte aligned, enabling memory-mapped access and integrity verification via CRC-32.

### Container Components and Segment Types

Each RVF file consists of typed segments identified by hexadecimal type codes. According to the source code in [`rvf_container.rs`](https://github.com/ruvnet/RuView/blob/main/rvf_container.rs), the following components are supported:

| Component | What it stores | RVF segment type |
|-----------|----------------|------------------|
| Manifest (model ID, version, creator) | JSON metadata | `0x05` |
| Model weights (raw f32 vector) | Binary `f32` array | `0x01` |
| Quantisation info | JSON (type, scale, zero point) | `0x06` |
| Vital-sign detector config | JSON (breathing/heart-rate bands, window size…) | `0x0B` |
| LoRA adaptation profiles | Name + f32 weight array | `0x0D` |
| HNSW index for hot-neuron lookup | Binary graph structure | `0x02` |
| Overlay graph (pre-computed geometry) | Binary adjacency lists | `0x03` |
| SONA environment-specific delta weights | JSON payload | `0x36` |
| Witness / training proof | JSON (hash, metrics) | `0x0A` |
| Optional WASM inference engine, UI assets, crypto signature | Binary blobs | `0x10`, `0x11`, `0x0C` |

### Segment Header Structure

Every segment begins with a fixed **64-byte header** (`SegmentHeader`) defined in [`rvf_container.rs`](https://github.com/ruvnet/RuView/blob/main/rvf_container.rs). This header contains:

- Magic number and version fields for format validation
- Segment type identifier (e.g., `0x01` for weights)
- Monotonically increasing `segment_id`
- Payload length in bytes
- CRC-32-based content hash (16 bytes)
- Padding to enforce 64-byte alignment

The alignment requirement ensures that segments can be memory-mapped efficiently and that SIMD operations on weight vectors are cache-line friendly.

## Building and Serializing RVF Containers

The `RvfBuilder` struct in [`rvf_container.rs`](https://github.com/ruvnet/RuView/blob/main/rvf_container.rs) provides a fluent API for constructing containers. The build workflow follows three stages:

1. **Create a builder** – `RvfBuilder::new()`.
2. **Push segments** – High-level helpers (`add_manifest`, `add_weights`, `add_quant_info`, …) call `push_segment`. Each call assigns a monotonically increasing `segment_id`, computes a 16-byte content hash from CRC-32 (`crc32_content_hash`), and calculates padding to the next 64-byte boundary (`align_up`).
3. **Serialize** – `build()` concatenates `[header | payload | padding]` for every segment, producing a raw `Vec<u8>` that can be written to disk via `write_to_file`.

The corresponding `RvfReader` validates the magic, version, and content hash during instantiation, exposing helpers such as `manifest()`, `weights()`, `lora_profile()`, and `segment_list()`.

## Progressive Loading Mechanism

Large Wi-Fi DensePose models can take seconds to read from disk and deserialize. RuView mitigates this with a **three-layer progressive loader** implemented in [`rvf_pipeline.rs`](https://github.com/ruvnet/RuView/blob/main/rvf_pipeline.rs).

### Three-Layer Architecture

The progressive loader splits model initialization into three distinct latency tiers:

| Layer | What is loaded | Typical latency |
|-------|----------------|-----------------|
| **A** (instant) | Manifest, segment directory, optional HNSW index (used only for hot-neuron discovery) | `< 5 ms` |
| **B** (warm) | Subset of weights belonging to "hot" neurons (first-layer nodes of the HNSW graph). If no index exists, the first 25% of the weight vector is used as a fallback. | ~ 30% of full load time |
| **C** (full) | All remaining weights, overlay graph, SONA profiles, and any optional assets. | Full model readiness |

### Implementation in rvf_pipeline.rs

The `ProgressiveLoader` struct is a thin wrapper around `RvfReader` that orchestrates the three layers:

- `ProgressiveLoader::new(data)` parses the whole file once to build the segment map.
- `load_layer_a()` extracts the manifest and calculates `n_segments`.
- `load_layer_b()` uses the HNSW index (`SEG_INDEX`, type `0x02`) to find hot neuron IDs, then extracts only those weight entries from the weights segment (`0x01`).
- `load_layer_c()` pulls the remaining payloads (full weight vector, overlay graph, LoRA profiles).

Progress is reported via `loading_progress()` (returning ≈ 0.33, 0.67, 1.0) and the current status can be queried with `layer_status()`.

### CLI and API Integration

The sensing server binary in [`main.rs`](https://github.com/ruvnet/RuView/blob/main/main.rs) exposes the progressive loader via the `--progressive` flag:

```bash

# Start the sensing server with progressive loading

target/release/sensing-server --model model.rvf --progressive

```

When the flag is present, the server initializes the `ProgressiveLoader` instead of blocking on full deserialization:

```rust
if args.progressive || args.model.is_some() {
    info!("Loading trained model (progressive) from {}", mp.display());
    let data = std::fs::read(&mp).expect("model file");
    progressive_loader = Some(ProgressiveLoader::new(&data).expect("loader"));
}

```

The REST API surfaces layer status through endpoints such as `/api/v1/models/info` and `/api/v1/models/progress`, allowing the web UI to display a spinner while Layer A and B are being parsed, then switching to full inference once Layer C completes.

## Full-Cycle Code Example

The following example demonstrates building an RVF container, persisting it to disk, and loading it progressively using the RuView APIs:

```rust
use rvf_container::{RvfBuilder, VitalSignConfig};

// 1️⃣ Build a model container
let mut builder = RvfBuilder::new();
builder.add_manifest("wifi-densepose-v1", "0.1.0", "Wi-Fi DensePose model");
builder.add_weights(&[0.1_f32, 0.2, 0.3]);               // tiny weight vector
builder.add_quant_info("int8", 0.0078, -128);
builder.add_vital_config(&VitalSignConfig::default());
// optional: HNSW index, overlay graph, LoRA profiles, witness …
let data = builder.build();          // `Vec<u8>` ready to ship

// 2️⃣ Persist to file (optional)
std::fs::write("model.rvf", &data)?;

// 3️⃣ Load with progressive loader
let loader = rvf_pipeline::ProgressiveLoader::new(&data)?;

// Layer A – manifest & quick UI feedback
let a = loader.load_layer_a()?;
// `a.model_name`, `a.version`, `a.n_segments` can be sent to the UI

// Layer B – hot-neuron subset for early inference
let b = loader.load_layer_b()?;
// `b.weights_subset` can be used for a lightweight preview model

// Layer C – full model for accurate inference
let c = loader.load_layer_c()?;
// `c.all_weights`, `c.overlay`, `c.sona_profiles` are now available

```

## Summary

- The **RVF model container architecture** bundles Wi-Fi DensePose models into a single file with 64-byte aligned segments, each validated by CRC-32 hashes.
- **Segment types** range from `0x01` (weights) to `0x0B` (vital-sign configs), enabling self-describing model artifacts.
- The **`RvfBuilder`** and **`RvfReader`** in [`rvf_container.rs`](https://github.com/ruvnet/RuView/blob/main/rvf_container.rs) handle deterministic serialization and integrity-checked deserialization.
- **Progressive loading** splits initialization into three layers: Layer A (manifest, <5 ms), Layer B (hot-neuron weights, ~30% load), and Layer C (full weights).
- The **`ProgressiveLoader`** in [`rvf_pipeline.rs`](https://github.com/ruvnet/RuView/blob/main/rvf_pipeline.rs) orchestrates layer loading, exposing progress via `loading_progress()` and `layer_status()`.
- CLI integration via `--progressive` flag and REST API endpoints enable real-time UI feedback during model startup.

## Frequently Asked Questions

### What is the RVF file format used for in RuView?

The RVF (RuView File) format is a single-file container designed to bundle all components required for Wi-Fi DensePose inference, including model weights, quantization parameters, HNSW indices, and vital-sign detector configurations. It replaces multiple scattered files with a self-describing, 64-byte-aligned binary format that supports integrity verification via CRC-32 hashes and enables memory-mapped access for efficient loading.

### How does progressive loading improve model startup time?

Progressive loading reduces time-to-first-inference by splitting model initialization into three layers: Layer A loads the manifest and segment directory in under 5 milliseconds to provide immediate UI feedback; Layer B loads only "hot" neuron weights (approximately 30% of the full model) to enable approximate inference; and Layer C loads remaining weights in the background. This architecture allows the RuView sensing server to begin processing requests before the entire model is resident in memory.

### What is the purpose of the 64-byte segment alignment in RVF containers?

The 64-byte alignment requirement for each RVF segment ensures that payload data begins on cache-line boundaries, which optimizes SIMD operations on weight vectors and enables efficient memory mapping on modern operating systems. This alignment is enforced by the `align_up` function in [`rvf_container.rs`](https://github.com/ruvnet/RuView/blob/main/rvf_container.rs), which calculates padding to the next 64-byte boundary after each segment's payload and content hash.

### How are hot neurons identified during Layer B loading?

Hot neurons are identified using the HNSW (Hierarchical Navigable Small World) index stored in segment type `0x02`, which maps to the first-layer nodes of the approximate nearest neighbor graph. If the HNSW index is present, `load_layer_b()` in [`rvf_pipeline.rs`](https://github.com/ruvnet/RuView/blob/main/rvf_pipeline.rs) extracts only the weight entries corresponding to these high-traffic neurons; if no index exists, the loader falls back to loading the first 25% of the weight vector as a generic warm-start subset.