docs: add control plane docs

Author: mwfarb

python/control_plane/README.md

@@ -0,0 +1,51 @@
+# AllSpark Control Plane
+
+This directory contains the NiceGUI-based reactive control plane for the AllSpark Edge Server.
+
+The control plane runs as a decoupled **sidecar** UI alongside the core edge network server. This separation ensures the high-throughput WebSocket operations of the main node remain unaffected by the UI data rendering.
+
+## Setup Requirements
+
+The control plane shares dependencies with the Python Edge Server. Ensure all dependencies are installed:
+
+```bash
+cd ../  # Navigate up to the python edge server root
+pip install -r requirements.txt
+```
+
+> **Note**: The core edge server must run to generate the default `config.json` before the control plane can read the settings correctly.
+
+## Running the Servers (Order of Operations)
+
+Because the control plane binds asynchronously and depends on the main edge configuration and API (`/api/status`), you should boot up the edge server **first**.
+
+**Step 1. Run the Core Edge Server**
+In your first terminal:
+```bash
+cd allspark_agent/edge_server/python
+python server.py
+```
+*You should see output indicating it is running on `http://0.0.0.0:8080` (and `wss://...`). If this is the first run, it will automatically generate a default `config.json` in the `edge_server/` root.*
+
+**Step 2. Run the Control Plane Sidecar**
+In a second terminal:
+```bash
+cd allspark_agent/edge_server/python
+python control_plane/main.py
+```
+*NiceGUI will automatically read your `config.json` and start the remote dashboard on `http://127.0.0.1:8081` (Edge Server Port + 1).*
+
+**Step 3. (Optional) Run the Mock Rerun.io Viewer**
+To populate the `/rerun` visualization iframe in the control plane dashboard with dummy data until the true data plane is integrated, launch the rerun mock script in a third terminal:
+```bash
+cd allspark_agent/edge_server/python
+python control_plane/dummy_rerun_server.py
+```
+*This will spin up a local rerun web viewer on port `9090` which the control plane will iFrame natively.*
+
+## Key Features
+
+1. **Reactive Dashboard:** Monitors your local MQTT anomaly topic streams on `127.0.0.1:1883` in real-time.
+2. **Client Health UI:** Actively polls the `/api/status` endpoint to display connected mobile rigs and trigger on-demand data uploads.
+3. **Capture Browser:** Traverses the local `.quic`, `.mp4`, and `.json` files inside your edge upload directory and streams them natively to the browser.
+4. **Agent Testing Stub:** Quick shortcut for sending anomalies to the main Agentic framework for resolution.

python/control_plane/architecture.md

@@ -0,0 +1,63 @@
+# AllSpark Edge Control Plane - Architecture & Design Decisions
+
+This document captures the core architectural choices and design patterns implemented for the AllSpark Edge Control Plane.
+
+## 1. Framework Selection: NiceGUI
+**Decision:** We chose [NiceGUI](https://nicegui.io/) over traditional decoupled SPA frameworks (like React, Vue, or Angular) or heavy template rendering (like Django/Jinja).
+**Rationale:** 
+- **Python-Native:** NiceGUI allows the entire frontend and backend logic to reside in pure Python. This ensures that the AI/backend engineers maintaining the AllSpark ecosystem can easily extend the UI without needing specialized frontend context switching.
+- **Reactive Data Binding:** It provides Vue-like reactivity natively in Python, making it trivial to auto-update lists, tables, and graphs without writing websocket/polling boilerplate manually.
+
+## 2. The Sidecar Architecture Pattern
+**Decision:** The control plane executes as a completely detached **Sidecar Process** (`python control_plane/main.py`) rather than being tightly integrated into the main `aiohttp` edge server (`server.py`).
+**Rationale:**
+- **Isolation of Concerns:** The primary Edge Server manages high-frequency WebSocket streams, large QUIC video blob uploads, and Bonjour service discovery. Keeping the UI rendering and polling decoupled ensures that an expensive UI redraw or long-running query doesn't block the asyncio event loop handling critical edge ingestion.
+- **Port Offset:** The sidecar automatically reads the Edge Server's configured port (e.g., `8080`) from `config.json` and binds itself to `port + 1` (e.g., `8081`), ensuring no port collisions while remaining predictable.
+
+## 3. Single Source of Truth Configuration
+**Decision:** Both the Edge Server and the Sidecar UI read from a unified `config.json` in the root `edge_server/` directory.
+**Rationale:** 
+- **Bootstrapping:** Whichever service boots first (typically `server.py` or the `node` equivalent) checks for `config.json`. If it's missing, it dynamically generates it with internal defaults.
+- **Synchronization:** The control plane reliably knows exactly where the `uploadPath` is located, what IP constraints exist, and what the base port is without duplicated environment variables.
+
+## 4. Integration Strategies for Edge Data
+
+We utilized three distinct strategies for populating the reactive UI, optimizing for speed and footprint:
+
+### A. Polling for Client State (REST API)
+- **Method:** `aiohttp` loop polling `/api/status` via `ui.timer(5.0)`.
+- **Reasoning:** Rather than constructing an inter-process WebSocket bridge between the Edge Server and the Sidecar to sync mobile rig connections, the sidecar leverages the Edge Server's existing lightweight REST API.
+
+### B. Shared File Mounts (Capture Browser)
+- **Method:** `os.path` and `glob` traversal to `app.add_media_files()`.
+- **Reasoning:** Instead of creating file transfer endpoints, the Sidecar reads the absolute system path defined in `config.json` (`uploads/orgs/default/...`). It dynamically builds UI cards based on what exists on disk in real-time, allowing native HTML5 `video` playback over HTTP immediately.
+
+### C. Direct Broker Attachment (MQTT Anomalies)
+- **Method:** Background `paho-mqtt` thread processing wildcard topics (`#`).
+- **Reasoning:** System anomalies generated by AllSpark agents bypass the core Edge Server entirely and hit the local MQTT broker (`1883`). The control plane runs a dedicated Paho subscriber thread that captures, structures, and limits anomaly events in memory, pushing updates to the UI natively.
+
+## 5. Rerun.io Data Plane Mocking
+**Decision:** Integrated an `iframe` pointing to a local `rerun-sdk` web viewer (`http://localhost:9090`).
+**Rationale:** Allows the control plane to seamlessly wrap complex, high-performance rust-rendered robotics 3D visualizations inside the standard Python UI workflow until a unified authentication and embedding pipeline is established.
+
+---
+
+## Next Steps & Future Work
+
+While Phase 1 and 2 established the decoupled control plane, the following steps are planned for the evolution of the AllSpark Edge architecture:
+
+1. **Native Integration (Merging the Sidecar):**
+   - Although the detached Sidecar pattern (running on `port + 1`) is currently used to guarantee the Edge Server's critical event loop remains unblocked, the ultimate goal is to **natively integrate** the control plane into the main Edge Server application. This will unify the deployment footprint and eliminate the need to run two separate Python processes.
+
+2. **Real Rerun.io Server Integration:**
+   - Replace the `dummy_rerun_server.py` mock with the actual `rerun-sdk` data integration pipeline. This involves piping the live telemetry and `.quic` video streams directly into the native Rerun data plane for real-time 3D and spatial debugging.
+
+3. **Expanded Configuration & Data Discovery:**
+   - Extend the `config.json` schema to encompass a broader range of telemetry locations and application logs.
+   - Update `pages/capture.py` to ingest and parse these diverse logs globally, providing a centralized diagnostic view beyond just the MQTT streams and media uploads.
+
+4. **Agentic Framework Hookup:**
+   - Replace the UI stubs in `pages/agent.py` with actual programmatic calls to the underlying AllSpark Agentic nodes. This will allow the control plane to seamlessly dispatch identified MQTT anomalies directly to the Vertex/LLM-Farm agents and display their diagnostic reports dynamically within the dashboard.
+
+5. **Unified Security & Authentication:**
+   - Sync the SSL context and authentication layers from the main Edge app into the control plane to ensure that remote debugging over the network is properly secured with JWT or token-based guards.