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

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.