# WiFi-Mat Disaster Response Module Architecture for Survivor Detection

> Explore the WiFi-Mat disaster response module architecture built with Rust and Domain-Driven Design. Discover real-time survivor detection using WiFi Channel State Information analysis across five key contexts.

- Repository: [rUv/wifi-densepose](https://github.com/ruvnet/wifi-densepose)
- Tags: architecture
- Published: 2026-02-16

---

**The WiFi-Mat disaster response module implements a Domain-Driven Design architecture in Rust, separating concerns into five bounded contexts—Detection, Localization, Alerting, Integration, and Domain Model—to enable real-time survivor detection via WiFi Channel State Information analysis.**

The `wifi-densepose-mat` crate extends the core `wifi-densepose` workspace to provide a production-ready disaster response system. This modular Rust implementation processes WiFi CSI data to extract vital signs, estimate 3-D positions, and generate prioritized alerts according to the START triage protocol.

## Domain-Driven Design Architecture

The WiFi-Mat architecture follows **Domain-Driven Design (DDD)** principles, organizing the system into well-defined bounded contexts that encapsulate specific disaster-response responsibilities. This separation ensures that complex signal processing details remain isolated from business logic and alerting policies.

### Bounded Contexts Overview

| Bounded Context | Responsibility | Key Types |
|-----------------|----------------|-----------|
| **Detection** | Real-time vital-sign extraction (breathing, heartbeat, movement) from CSI data | `DetectionPipeline`, `BreathingDetector`, `HeartbeatDetector`, `MovementClassifier`, `DetectionConfig` |
| **Localization** | 3-D survivor position estimation using triangulation, fingerprinting and depth inference | `LocalizationService`, `Triangulator`, `DepthEstimator`, `PositionFuser` |
| **Alerting** | Prioritised survivor-alert generation and dispatch (START-protocol compatible) | `AlertGenerator`, `AlertDispatcher`, `AlertConfig`, `PriorityCalculator` |
| **Integration (Anti-corruption Layer)** | Adapts existing *wifi-densepose* signal and neural-network crates, hides hardware specifics | `SignalAdapter`, `NeuralAdapter`, `HardwareAdapter` |
| **Domain Model** | Core entities that capture disaster events, zones, survivors, vital-sign readings, triage status, etc. | `DisasterResponse`, `DisasterEvent`, `ScanZone`, `Survivor`, `VitalSignsReading`, `TriageStatus` |

## Core System Components

The architecture centers on the `DisasterResponse` orchestrator, which coordinates specialized services across the bounded contexts. Each service operates independently through well-defined interfaces, enabling testing and extension without cross-context dependencies.

### Detection Pipeline

Located in [`src/detection/pipeline.rs`](https://github.com/ruvnet/wifi-densepose/blob/main/src/detection/pipeline.rs), the `DetectionPipeline` aggregates three specialized detectors to process raw CSI data:

- **`BreathingDetector`** ([`src/detection/breathing.rs`](https://github.com/ruvnet/wifi-densepose/blob/main/src/detection/breathing.rs)): Implements FFT-based breathing-rate extraction and pattern classification to identify respiratory signatures in signal amplitude variations.
- **`HeartbeatDetector`**: Extracts cardiac rhythms from micro-Doppler shifts in phase data.
- **`MovementClassifier`**: Distinguishes between stationary survivors and environmental noise or debris movement.

The pipeline supports optional ML enhancement via `MlDetectionPipeline` when `enable_ml` is set in `DetectionConfig`, leveraging the neural-network crate through the `NeuralAdapter`.

### Localization Service

The `LocalizationService` in `src/localization/*.rs` fuses multiple positioning techniques to produce robust 3-D estimates:

- **`Triangulator`**: Calculates position using time-of-flight and angle-of-arrival from multiple WiFi access points.
- **`DepthEstimator`**: Applies depth-inference models to CSI amplitude patterns to estimate vertical position.
- **`PositionFuser`**: Combines triangulation and depth estimates with fingerprinting data to refine accuracy and confidence bounds.

### Alerting System

The `AlertDispatcher` in `src/alerting/*.rs` implements START-protocol-compatible triage:

- **`PriorityCalculator`**: Assigns priority levels (Immediate, Delayed, Minor, Deceased) based on vital-sign stability and confidence scores.
- **`AlertGenerator`**: Creates structured `Alert` entities containing survivor position, triage status, and vital-sign history.
- **Dispatch Channels**: Supports WebSocket, MQTT, and other protocols for integration with emergency management systems.

### Integration Layer

The anti-corruption layer in `src/integration/*.rs` isolates the domain model from external dependencies:

- **`SignalAdapter`**: Normalizes CSI data from various WiFi hardware implementations.
- **`NeuralAdapter`**: Bridges the domain model with the `wifi-densepose` neural-network inference crate.
- **`HardwareAdapter`**: Abstracts USB, PCIe, and network-attached WiFi radios.

## Data Flow and Processing Pipeline

The WiFi-Mat architecture implements an event-driven workflow that processes disaster scenarios through five distinct stages:

1. **Configuration** – A `DisasterConfig` builder defines disaster type, sensitivity thresholds, confidence levels, and scan intervals. The `DisasterResponse::new` constructor initializes the orchestrator with detection, localization, and alerting services.

2. **Event Initialization** – `DisasterResponse::initialize_event` creates a `DisasterEvent` entity representing the specific incident. `add_zone` registers `ScanZone` geometries that define geographic search areas.

3. **Scanning Loop** – `start_scanning` runs an async `scan_cycle` loop. For each zone, CSI data feeds into `DetectionPipeline::process_zone`, which executes breathing, heartbeat, and movement detection algorithms.

4. **Domain Event Recording** – When `VitalSignsReading` is produced, `LocalizationService::estimate_position` fuses triangulation and depth models for 3-D positioning. The `DisasterEvent` records the detection as a `Survivor` entity with triage status calculated by `TriageCalculator`.

5. **Alert Generation** – `Survivor::should_alert` checks priority thresholds. Valid alerts trigger `AlertDispatcher::generate_alert` to create START-protocol prioritized notifications dispatched via WebSocket or MQTT channels.

## Implementation Reference

The WiFi-Mat crate organizes source code according to DDD principles with clear module boundaries:

| File | Role |
|------|------|
| [`src/lib.rs`](https://github.com/ruvnet/wifi-densepose/blob/main/src/lib.rs) | Public API exposing `DisasterResponse`, `DisasterConfig`, and core re-exports |
| `src/domain/*.rs` | Domain entities: `Survivor`, `DisasterEvent`, `ScanZone`, `VitalSignsReading`, `TriageStatus` |
| [`src/detection/pipeline.rs`](https://github.com/ruvnet/wifi-densepose/blob/main/src/detection/pipeline.rs) | `DetectionPipeline` orchestrating vital-sign extraction |
| [`src/detection/breathing.rs`](https://github.com/ruvnet/wifi-densepose/blob/main/src/detection/breathing.rs) | FFT-based breathing detection implementation |
| `src/localization/*.rs` | `LocalizationService`, `Triangulator`, `DepthEstimator`, `PositionFuser` |
| `src/alerting/*.rs` | `AlertGenerator`, `AlertDispatcher`, `AlertConfig`, `PriorityCalculator` |
| `src/integration/*.rs` | Anti-corruption adapters: `SignalAdapter`, `NeuralAdapter`, `HardwareAdapter` |
| [`docs/adr/ADR-001-wifi-mat-disaster-detection.md`](https://github.com/ruvnet/wifi-densepose/blob/main/docs/adr/ADR-001-wifi-mat-disaster-detection.md) | Architectural Decision Record documenting DDD layout |
| [`examples/mat-dashboard.html`](https://github.com/ruvnet/wifi-densepose/blob/main/examples/mat-dashboard.html) | Frontend visualization demo for detection zones |

## Code Examples

### Initialize the Disaster Response System

```rust
use wifi_densepose_mat::{
    DisasterResponse, DisasterConfig, DisasterType,
    ScanZone, ZoneBounds,
};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Build configuration
    let config = DisasterConfig::builder()
        .disaster_type(DisasterType::Earthquake)
        .sensitivity(0.85)
        .confidence_threshold(0.6)
        .max_depth(4.0)
        .scan_interval_ms(300)
        .build();

    // Create response coordinator
    let mut response = DisasterResponse::new(config);

    // Initialise a disaster event
    response.initialize_event(
        geo::point! { x: 0.0, y: 0.0 },
        "Building collapse in downtown",
    )?;

    // Add a scan zone
    let zone = ScanZone::new(
        "Sector-A",
        ZoneBounds::rectangle(0.0, 0.0, 30.0, 20.0),
    );
    response.add_zone(zone)?;
    
    // Start the async scanning loop
    response.start_scanning().await?;
    Ok(())
}

```

### Manually Invoke the Detection Pipeline

```rust
use wifi_densepose_mat::{
    detection::{DetectionPipeline, DetectionConfig},
    domain::VitalSignsReading,
};

let config = DetectionConfig::default();
let pipeline = DetectionPipeline::new(config);

// Simulated CSI buffers (amplitudes & phases) – in real use these come from hardware
let amplitudes = vec![/* ... */];
let phases = vec![/* ... */];

// Add data to the internal buffer
pipeline.add_data(&amplitudes, &phases);

// Process a dummy zone (the zone only provides geometry for localisation)
let dummy_zone = wifi_densepose_mat::domain::scan_zone::ScanZone::new(
    "test-zone",
    wifi_densepose_mat::domain::scan_zone::ZoneBounds::rectangle(0.0, 0.0, 10.0, 10.0),
);
if let Some(reading) = pipeline.process_zone(&dummy_zone).await? {
    println!("Detected vital signs: {:?}", reading);
}

```

### Generate and Dispatch Survivor Alerts

```rust
use wifi_densepose_mat::alerting::{AlertDispatcher, AlertConfig};

let alert_cfg = AlertConfig::default();
let dispatcher = AlertDispatcher::new(alert_cfg);

// Assume `survivor` is a `Survivor` obtained from a detection event
let alert = dispatcher.generate_alert(&survivor)?;
dispatcher.dispatch(alert).await?;

```

## Summary

- The **WiFi-Mat disaster response module** implements a **Domain-Driven Design** architecture in Rust, separating concerns into five bounded contexts: Detection, Localization, Alerting, Integration, and Domain Model.
- The **DetectionPipeline** in [`src/detection/pipeline.rs`](https://github.com/ruvnet/wifi-densepose/blob/main/src/detection/pipeline.rs) orchestrates vital-sign extraction through specialized detectors for breathing, heartbeat, and movement, with optional ML enhancement via the `NeuralAdapter`.
- **3-D survivor positioning** relies on the `LocalizationService`, which fuses triangulation, depth estimation, and fingerprinting to produce robust position estimates within defined `ScanZone` geometries.
- The **event-driven workflow** progresses through configuration, event initialization, async scanning loops, domain event recording, and START-protocol-compatible alert dispatch via `AlertDispatcher`.
- **Extensibility** is achieved through trait-based plug-in detectors, anti-corruption adapters in `src/integration/*.rs`, and hardware abstraction that isolates the domain model from specific WiFi radio implementations.

## Frequently Asked Questions

### What is the WiFi-Mat module and how does it detect survivors?

The WiFi-Mat (Mass Casualty Assessment Tool) module is a Rust-based disaster response system that detects survivors by analyzing WiFi Channel State Information (CSI) data. It extracts vital signs including breathing rates, heartbeats, and micro-movements using FFT-based algorithms in [`src/detection/breathing.rs`](https://github.com/ruvnet/wifi-densepose/blob/main/src/detection/breathing.rs) and related detectors, then localizes survivors in 3-D space through triangulation and depth estimation.

### How does the architecture separate concerns between detection and alerting?

The architecture implements Domain-Driven Design with distinct bounded contexts. The **Detection** context in `src/detection/*.rs` handles signal processing and vital-sign extraction, producing `VitalSignsReading` entities. The **Alerting** context in `src/alerting/*.rs` consumes these domain events through `AlertGenerator` and `PriorityCalculator`, creating START-protocol prioritized alerts without direct dependency on the signal processing implementation.

### Can the system work with different WiFi hardware implementations?

Yes, the **Integration** bounded context in `src/integration/*.rs` provides an anti-corruption layer that abstracts hardware specifics. The `SignalAdapter`, `NeuralAdapter`, and `HardwareAdapter` traits allow the system to interface with various WiFi radios (USB, PCIe, or network-attached) without modifying the core domain logic in `src/domain/*.rs` or detection algorithms.

### What triage protocol does WiFi-Mat use for prioritizing survivors?

The system implements the **START (Simple Triage and Rapid Treatment)** protocol through the `PriorityCalculator` in `src/alerting/*.rs`. Based on vital-sign stability, confidence scores, and movement detection, survivors are categorized as Immediate (red), Delayed (yellow), Minor (green), or Deceased (black), ensuring that rescue teams receive prioritized alerts matching standard emergency medical response procedures.