Integrations, plugins, deployment, and observability
Overview
This area is the repository's external-operation surface: prototype integrations under integrations/, the Claude/Codex operator plugin under plugins/ruview/, container and Kubernetes-oriented deployment files under docker/, .github/, monitoring/, and logging/, plus release/archive/reference surfaces that affect what operators can safely run or publish.
The iPhone LiDAR integration is split into native capture and a local browser relay. integrations/…/LiDARCaptureManager.swift starts an ARWorldTrackingConfiguration with .sceneDepth or .smoothedSceneDepth, extracts ARDepthData.depthMap, confidence, camera intrinsics, and camera pose, and never reads RGB frames. integrations/…/RuViewFrame.swift labels frames as type/schema=ruview.lidar.depth.v1, source=live, and privacyClass=geometry-only. integrations/…/WebSocketStreamer.swift downsamples each frame, encodes depth as little-endian UInt16 millimeters plus UInt8 confidence, throttles to 15 FPS by timestamp, and sends JSON over ws:// or wss://. integrations/…/relay.mjs is the development entrypoint (npm start): it serves only index.html, app.mjs, codec.mjs, and styles.css, requires a per-run or RUVIEW_LIDAR_TOKEN query token for /ws/lidar, bounds WebSocket payloads at 2 MB, and forwards only packets whose type is ruview.lidar.depth.v1. The browser viewer in integrations/…/app.mjs connects back to the relay with the token, decodes frames through integrations/…/codec.mjs, converts depth to a point cloud using scaled intrinsics, and renders it to a canvas.
The virtual-view integration is an opt-in cross-repository prototype. integrations/…/adapter.mjs exports createVirtualViewAdapter({ broker, privateKey, enabled }); when disabled it returns BLOCK, and when enabled it performs a bounded plain-JSON structural preflight before handing a schema: "virtual-view.v1", frame: "room_enu" snapshot to the injected Dream Machine broker. It deliberately imports no hardware, network, or model client and sets hardwareActuation: false. integrations/…/README.md documents the companion Dream Machine commit and states that raw RF spatial.evidence.v1 or LiDAR ruview.lidar.depth.v1 packets are not accepted as this adapter's scene contract.
The RuView plugin packages operator workflows for Claude Code and mirrors command prompts for Codex. plugins/…/plugin.json defines the plugin metadata and an rvagent MCP server launched through npx -y @ruvnet/rvagent with RVAGENT_SENSING_URL=http://localhost:3000; skills, commands, and agents are auto-discovered from plugins/ruview/skills/, plugins/ruview/commands/, and plugins/ruview/agents/ rather than enumerated in the manifest. plugins/…/0001-ruview-plugin-contract.md is the contract: one mega-plugin listed from the repo-root marketplace, ruview-* namespace ownership, shell-first allowed tools, and full command parity for Codex prompts. plugins/…/smoke.sh is the structural gate: it checks the root marketplace source, plugin manifest fields, frontmatter for skills/commands/agents, absence of wildcard allowed tools, README compatibility/namespace sections, ADR status, and command-to-Codex prompt parity. plugins/…/AGENTS.md scopes Codex prompt behavior: default read-only exploration, preserve evidence labels, no credential emission, and use the published @ruvnet/ruview harness for agent runs that need sandboxing and redaction.
The primary local deployment entrypoint is docker/docker-compose.yml. It builds the Rust sensing server from docker/Dockerfile.rust, publishes REST and WebSocket ports on loopback (127.0.0.1:3000, 127.0.0.1:3001), publishes ESP32 UDP on 5005/udp, and passes through CSI_SOURCE, MODELS_DIR, RUVIEW_API_TOKEN, UDP source-guard settings, and SENSING_ALLOWED_HOSTS. The same compose file can build a legacy Python WebSocket service from docker/Dockerfile.python, which copies archive/v1/ and runs python -m v1.src.sensing.ws_server. docker/Dockerfile.rust builds sensing-server, cog-ha-matter, and homecore-server from the v2 workspace, includes the UI assets, and fails the image build if key UI files/directories are absent. docker/docker-entrypoint.sh is the runtime policy gate: it refuses the default sensing-server path when RUVIEW_API_TOKEN is unset and the HTTP bind is routable unless RUVIEW_ALLOW_UNAUTHENTICATED is explicitly set, routes cog-ha-matter and homecore-server subcommands to their binaries, and binds UDP on 0.0.0.0 only when RUVIEW_UDP_ALLOW, RUVIEW_UDP_INSECURE_LAN, or an explicit UDP guard is present. docker/otel-compose.yml is the observability demo stack: it builds the server with SENSING_FEATURES=mqtt,otel, points OTEL_EXPORTER_OTLP_ENDPOINT at otel-collector, and sends logs through docker/otel-collector.yaml to an Ourios backend queryable on localhost port 4319.
Production-facing observability is described by standalone Prometheus, Grafana, and Fluentd manifests. monitoring/prometheus-config.yml scrapes Kubernetes infrastructure, wifi-densepose pods in wifi-densepose and wifi-densepose-staging, PostgreSQL and Redis exporters, ingress, blackbox probes for https://wifi-densepose.com and staging, and remote-writes filtered samples to a monitoring service. monitoring/alerting-rules.yml expects metric names such as http_requests_total, http_request_duration_seconds_bucket, wifi_densepose_data_processed_total, and wifi_densepose_model_inference_duration_seconds_bucket for application, infrastructure, database, Redis, security, and product alerts. monitoring/grafana-dashboard.json visualizes the same Prometheus job labels and metrics with namespace/pod/instance variables. logging/fluentd-config.yml installs a logging namespace, a Fluentd DaemonSet with read-only Kubernetes metadata RBAC, tailing of var/…/*.log, WiFi-DensePose log enrichment and severity routing, Prometheus metrics on port 24231, Elasticsearch outputs for errors/warnings/info/system logs, and S3 plus stdout backup for unmatched logs.
RuView's OpenTelemetry naming contract lives in semconv/. semconv/…/manifest.yaml names the custom registry and pins the upstream OpenTelemetry semantic-conventions dependency. semconv/…/events.yaml defines curated event names such as ruview.node.online, ruview.csi.stats, ruview.presence.changed, ruview.vitals.estimate, ruview.mqtt.error, and ruview.model.loaded; semconv/…/attributes.yaml defines shared attributes such as ruview.node.id, ruview.csi.source, presence/motion state enums, vitals estimates, and ruview.model.id. semconv/…/ruview-0.1.0.yaml publishes the initial schema URL. .github/…/semconv.yml installs a pinned OpenTelemetry Weaver release, validates semconv/registry, regenerates v2/…/semconv.rs, runs rustfmt, and fails if the generated constants drift.
GitHub workflows provide release, deployment, and external validation gates. .github/…/sensing-server-docker.yml is the canonical Docker publish workflow: on main/tag/manual runs it builds docker/Dockerfile.rust, pushes multi-arch images to GHCR and optionally Docker Hub, then smoke-tests UI assets, unauthenticated LAN mode, and bearer-token auth against the just-pushed image. .github/…/cd.yml deploys an existing GHCR image tag to staging or production Kubernetes namespaces, runs health checks, and can roll back via kubectl rollout undo. .github/…/pip-release.yml builds and publishes wifi-densepose and ruview Python packages only on manual dispatch or v*-pip tags, and enforces the committed ADR-117 witness hash before v2 publishing. .github/…/npm-packages.yml gates the published Node package surfaces under harness/ and tools/ with install/build/test, pack-size and source-map checks, tarball smoke tests, and README claim-checking. .github/…/firmware-ci.yml builds ESP32 firmware variants, verifies release tag/version consistency, packages checksummed firmware bundles, and publishes v*-esp32 prereleases; .github/…/firmware-qemu.yml builds Espressif QEMU, runs mock-firmware smoke/fuzz/NVS/swarm tests, and uploads logs. .github/…/iphone-lidar.yml tests the LiDAR web relay and codec on Node and compiles the Swift sources against the iOS 17 SDK. .github/…/security-scan.yml, .github/dependabot.yml, .github/…/csi-data-policy.yml, .github/…/model-release-gate.yml, .github/…/mqtt-integration.yml, and .github/…/verify-pipeline.yml cover dependency/security scanning, raw CSI data policy, model-gate regression coverage, MQTT broker integration, and the still-live deterministic Python proof.
Archive and reference surfaces are not maintained product entrypoints. archive/…/DEPRECATED.md and the banner in archive/…/README.md mark the original Python tree as frozen research code superseded by the Rust v2/ workspace and the wifi-densepose/ruview wheels; the only explicitly live artifact there is the ADR-028 deterministic proof under archive/v1/data/proof/. references/README.md and references/WiFi-DensePose-README.md are reference/research material with historical claims and illustrative code, not the operational contract. CHANGELOG.md is the release narrative and is where many external claims and package-release notes are recorded. NOTICE calls out vendored MediaTek/OpenWrt CSI patch licensing that is outside the repository's main license, while LICENSE is the MIT license text for the repository.
Coupling
- If the LiDAR wire schema changes, update both native and web halves together: integrations/…/RuViewFrame.swift fixes the
ruview.lidar.depth.v1type/provenance fields, integrations/…/WebSocketStreamer.swift fixes theu16le-mm+u8-confidencepayload shape, and integrations/…/codec.mjs rejects unknown types, encodings, invalid intrinsics, invalid pose arrays, and non-canonical base64. - If the LiDAR relay is exposed beyond a trusted development LAN, do not rely on integrations/…/relay.mjs token checks alone: integrations/…/README.md explicitly says
ws://does not encrypt the token and production must terminate TLS, authenticate sensor identity, convert frames into RuView observations, and attach witness receipts before fusion or persistence. - If virtual-view broker inputs are expanded, keep integrations/…/adapter.mjs and the companion broker contract in lockstep: this adapter only verifies bounded plain JSON plus
schema=virtual-view.v1andframe=room_enu; full geometry/provenance/signing validation remains the injected broker's responsibility. - If plugin commands are added, renamed, or removed, update both plugins/…/<name>.md and plugins/…/<name>.md; plugins/…/smoke.sh checks presence parity but plugins/…/0001-ruview-plugin-contract.md notes it does not prove content parity.
- If plugin discovery or marketplace layout changes, update plugins/…/0001-ruview-plugin-contract.md, plugins/…/README.md, and plugins/…/smoke.sh together: the smoke script assumes a repo-root .claude-plugin/marketplace.json, no skills/commands/agents arrays in plugins/…/plugin.json, and auto-discovery from the plugin directory tree.
- If Docker startup defaults are changed, verify docker/docker-compose.yml, docker/docker-entrypoint.sh, and
docker/Dockerfile.rusttogether. The compose file documents auth, UDP source guards, model directory, and CSI source behavior; the entrypoint enforces auth and UDP bind posture; the Dockerfile controls which binaries and UI assets actually ship. - If metric names or labels change in the sensing server, update monitoring/alerting-rules.yml, monitoring/grafana-dashboard.json, and monitoring/prometheus-config.yml together. The alerts and dashboard hard-code
job="wifi-densepose-app"and metric names such ashttp_requests_total,http_request_duration_seconds_bucket, andwifi_densepose_*. - If curated tracing event names or attributes change, treat semconv/…/*.yaml, the generated v2/…/semconv.rs, and .github/…/semconv.yml as one contract. The workflow intentionally fails on generated-code drift.
- If package release versions move, keep release workflows and public notes aligned: .github/…/pip-release.yml enforces lock-step
wifi-densepose/ruviewPython metadata, .github/…/npm-packages.yml enforces package tarball surfaces, .github/…/desktop-release.yml names desktop artifacts from workflow inputs, and CHANGELOG.md records what is actually published versus merely prepared. - If archive/v1 files are referenced by CI or docs, preserve the deprecation boundary in archive/…/DEPRECATED.md: most archive checks in .github/…/ci.yml are continue-on-error hygiene, but .github/…/verify-pipeline.yml still treats archive/…/verify.py as a live deterministic proof.
Risks
- monitoring/prometheus-config.yml lists recording-rules.yml under
rule_files, but the coveredmonitoring/tree contains only prometheus-config.yml, alerting-rules.yml, and grafana-dashboard.json. A Prometheus deployment using this file as-is can fail rule loading or start without the expected recording-rule file. docker/Dockerfile.ruststill comments thatCSI_SOURCE=autofalls back to simulation, while docker/docker-compose.yml and docker/docker-entrypoint.sh describe the safer fail-loud behavior unless synthetic data is explicitly selected. Operators following the Dockerfile comment can believe they are seeing real fallback behavior when the entrypoint/runtime contract is different.- .github/…/cd.yml validates production green pods with
curl http://localhost:8000/healthand/api/v1/info, while the Docker runtime in docker/docker-entrypoint.sh starts the sensing server on HTTP port 3000 by default and docker/docker-compose.yml publishes3000. If the Kubernetes deployment uses the current sensing-server image without an 8000-port override, traffic-switch validation can fail even when the image is healthy. - plugins/…/0001-ruview-plugin-contract.md states the Codex mirror smoke only checks command/prompt presence parity, not semantic parity. A changed operator command under
plugins/ruview/commands/can drift fromplugins/ruview/codex/prompts/while plugins/…/smoke.sh still passes. - integrations/…/relay.mjs forwards any authenticated text packet with
type: "ruview.lidar.depth.v1"to all other clients without validating the full payload; malformed frames are rejected only by the browser decoder in integrations/…/codec.mjs. A bad or hostile authenticated peer can therefore cause viewer-side frame errors and reconnect churn even though relay authentication passed.