## 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.