## Context

Unifying the Raspberry Pi 3B (1GB RAM) into a dedicated projection mapping appliance. The system must be entirely headless, controllable via any browser-enabled device on the same network.

## Goals / Non-Goals

**Goals:**
- Provide a "one-liner" setup script that installs the entire stack.
- Enable real-time remote manipulation of mapping surfaces via WebSockets.
- Implement a robust system for media management and system monitoring.
- Maintain a permanent WiFi AP while allowing connection to external networks (Hybrid Mode).

**Non-Goals:**
- **Audio Support**: Explicitly out of scope for the Pi 3B in this version.
- **Pi 4/5 Support**: Target hardware is strictly Pi 3B for this design.
- **Multi-Projector Sync**: Synchronizing multiple Pi units is not part of this version.

## Decisions

### 1. Real-Time Communication (WebSockets)
We will use **Socket.io** for all vertex and surface updates. This bypasses the overhead of HTTP and allows the browser to feel like a direct remote for the `ofxPiMapper` engine.

### 2. Networking Architecture (Permanent AP)
- **Primary**: The Pi acts as an Access Point (`MPVJ-AP`) on `wlan0`.
- **Secondary**: A virtual interface or shared `wlan0` configuration will allow connecting to venue WiFi.
- **Safety**: The AP never turns off, ensuring you can always reach the UI even if the venue WiFi fails.

### 3. Media Assignment & Validation
The Node.js backend will maintain a JSON manifest of mapping surfaces and their assigned sources.
- **Validation**: On upload, the backend will use `ffprobe` to verify the codec (H.264 required) and resolution (Warn if > 1080p).
- **Resource Warning**: The UI will display a "High Load" warning if multiple 1080p videos are assigned, recommending 720p for stable multi-surface playback.

### 4. Graphics & Build Strategy (The "Source-First" Build)
To handle the "Highlight Surface" functionality, we will modify the `ofxPiMapper` C++ source code to include a `/ofxPiMapper/surface/highlight` OSC listener.
- **Build Safety**: The setup script will increase the swap file to 2GB during the ~1 hour compilation to prevent OOM panics on the Pi 3B.
- **Binary Fallback**: The script will accept an optional argument to point to a pre-compiled binary if available.

### 5. Log & Data Streaming
- **Log Throttling**: The backend will buffer and throttle the `stdout` stream (max 10 lines per 500ms) to prevent WebSocket congestion.
- **State Persistence**: A explicit "Save Mapping" button in the UI will trigger the `/ofxPiMapper/save` OSC command to persist changes to the `settings.xml` file.

## Risks / Trade-offs

- **[Risk] RAM Exhaustion** → **Mitigation**: Use Preact/Vite for a lightweight frontend, set `NODE_OPTIONS="--max-old-space-size=512"`, and force `npm jobs=1`.
- **[Risk] WiFi Interference** → **Mitigation**: Prioritize the WebSocket channel for vertex movements.
- **[Risk] ofxPiMapper Build Time** → **Mitigation**: Attempt to pull pre-compiled binaries first; if building from source, notify the user of the 1-hour duration.