Initial commit of my folder

openspec/changes/mpvj-headless-control-center/design.md

@@ -0,0 +1,39 @@
+## Context
+
+The project aims to modernize the control interface for `ofxPiMapper` on the Raspberry Pi 3B. Currently, users rely on legacy PHP scripts (PocketVJ) or a local monitor/keyboard. The Pi 3B has significant resource constraints (1GB RAM, older CPU), requiring a highly efficient headless solution.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Provide a responsive, headless mapping UI accessible via browser.
+- Enable real-time remote manipulation of mapping surfaces via OSC.
+- Implement a robust system for media management and system monitoring.
+- Ensure the system is lightweight enough to run alongside `ofxPiMapper` on a Pi 3B.
+
+**Non-Goals:**
+- **Automatic Calibration**: Computer-vision based auto-mapping is explicitly out of scope for this version.
+- **Multi-Projector Sync**: Synchronizing multiple Pi units is not part of this design.
+- **Advanced Video Effects**: Real-time shaders or complex video processing beyond what `ofxPiMapper` provides.
+
+## Decisions
+
+### 1. Technology Stack
+- **Frontend**: React (using Vite for fast development and lean production builds).
+- **Backend**: Node.js with Express. Node.js is chosen for its excellent asynchronous handling of WebSockets and its mature OSC libraries (`node-osc`).
+- **Communication**: WebSockets (Socket.io) will be used for the frontend-to-backend real-time vertex updates to minimize latency compared to REST.
+
+### 2. OSC Bridge Architecture
+The Node.js server will act as a transparent bridge. It will listen for WebSocket events from the UI and immediately translate them into UDP OSC packets directed at `localhost:9999` where `ofxPiMapper` is listening.
+
+### 3. Headless Networking
+- **mDNS**: `avahi-daemon` will be configured to provide `mpvj.local` access.
+- **Access Point**: `hostapd` and `dnsmasq` will be managed via shell scripts triggered by the Node.js API to allow the user to toggle between AP and Client modes.
+
+### 4. Media Storage
+Media will be stored in `/home/pi/media`. The Node.js API will provide a file-browser endpoint and handle `multipart/form-data` uploads.
+
+## Risks / Trade-offs
+
+- **[Risk] RAM Exhaustion on Pi 3B** → **Mitigation**: We will use a "lite" version of the React frontend (potentially Preact) and keep Node.js dependencies to a minimum. We will also monitor memory usage via the dashboard.
+- **[Risk] WiFi Latency in AP Mode** → **Mitigation**: We will prioritize WebSocket traffic for vertex movements and use binary formats if necessary to reduce overhead.
+- **[Risk] ofxPiMapper Crash** → **Mitigation**: The Node.js API will monitor the process and provide a "Restart Mapper" button in the UI.