K11 Production System Architecture -- Master Plan

K11 Production System Architecture -- Master Plan

_Generated 2026-04-27 via Evo3 (Research -> 6 Divergent Paths -> Compound Synthesis -> Expand + Master Plan)._
_Full evolution output: Desktop/evo-cube-output/k11-production-system-architecture/_

---

Architecture Decision

Three-tier hybrid architecture combining NSSM services for headless publishers, Task Scheduler for GPU-bound Unity, and Sony's native mocopi PC app for BT sensor management. New LUMM wire format (0x4C554D4D) carries 27-bone skeletal data as a 772-byte fixed datagram on :9702.

Rejected alternatives:
- Monolith (everything in Unity) -- kills audio latency win, no cross-machine flexibility
- Docker -- USB/BT passthrough impossible, massive overkill for 3 Python scripts
- MotionMix-centric (K11 as sensor bridge) -- breaks product premise of self-contained hardware
- Full microservice (Unity as NSSM service) -- GPU inaccessible from Session 0

---

System Architecture

                    K11 Pod (Windows 11 Pro)
+-----------------------------------------------------------+
|                                                             |
|  TIER 1: NSSM Services (pre-login, auto-restart)           |
|  +-----------+  +-----------+  +-------------------+       |
|  | lume-depth|  | lume-audio|  | lume-inspector    |       |
|  | :9700 LUMD|  | :9701 LUMF|  | listens all ports |       |
|  +-----------+  +-----------+  +-------------------+       |
|                                                             |
|  TIER 2: User Session (GPU/BT, Task Scheduler at-login)    |
|  +---------------------+  +--------------------+           |
|  | Unity lume_pcloud.exe|  | Sony mocopi PC app |           |
|  | 11 components        |  | 6x BLE sensors    |           |
|  | Consumes :9700-9702  |  | -> :12351 binary   |           |
|  | HDMI -> Display      |  +--------------------+           |
|  +---------------------+                                   |
|                                                             |
|  TIER 3: Bridge (user session -> NSSM after proven)        |
|  +-----------------------------------+                     |
|  | mocopi_bridge.py                   |                     |
|  | Listens :12351 (Sony) + :9500 (OSC)|                     |
|  | Publishes LUMM -> :9702 ([ip]) |                     |
|  +-----------------------------------+                     |
|                                                             |
|  Hardware: Femto Bolt (USB-C), UMA-8 (USB-A), BT 5.x      |
+-----------------------------------------------------------+
         |              |              |
         | Tailscale mesh (all publishers bind [ip])
         v              v              v
+----------------------------------------------+
| MotionMix iOS                                 |
| LummReceiver.swift (NEW) <- :9702 LUMM        |
| MocopiReceiver.swift     <- :9500 OSC (fallback)|
| -> MocopiFeatureExtractor -> 128D [76:100]    |
+----------------------------------------------+

---

Port Map

---

LUMM Wire Format Specification

Magic: `0x4C554D4D` ('LUMM', little-endian). Port: `:9702`.

struct Header {             // 16 bytes
    u32 magic;              // 0x4C554D4D
    u32 frame;              // monotonic per-publisher
    u16 bone_count;         // 27 for mocopi v1
    u16 flags;              // bit 0: has_quaternion, bit 1: has_position
                            // bit 2: is_calibrated, bits 3-15: reserved
    f32 dt_seconds;         // wall-time delta since prior frame
};

struct BoneTransform {      // 28 bytes per bone
    f32 position[3];        // x, y, z (local, parent-relative)
    f32 quaternion[4];      // x, y, z, w (local rotation)
};

Total datagram: 16 + 27*28 = 772 bytes (fixed, no chunking, sub-MTU)

Bone ordering: Sony mocopi IDs 0-26 (root, spine, chest, neck, head, shoulders, arms, hands, legs, feet, toes, fingers).

---

File Structure (K11 deployment)

C:\Users\lume\lume\
+-- software\demo\
|   +-- audio_pub.py              # UNCHANGED
|   +-- pointcloud_pub.py         # UNCHANGED
|   +-- lume_packet_inspector.py  # +LUMM magic in MAGIC dict
|   +-- mocopi_bridge.py          # NEW (~200 lines)
|   +-- lume_wire_format.md       # +LUMM section
|   +-- tests\
|   |   +-- test_mocopi_bridge.py # NEW
|   +-- unity\lume_pcloud\
|       +-- Assets\Scripts\
|       |   +-- LumeMocopiReceiver.cs  # NEW (~120 lines)
|       |   +-- [10 existing .cs]      # UNCHANGED
|       +-- Builds\Windows\
|           +-- lume_pcloud.exe
+-- scripts\k11\
|   +-- install-services.ps1      # NEW
|   +-- uninstall-services.ps1    # NEW
|   +-- health-check.ps1          # NEW
|   +-- firewall-rules.ps1        # NEW
|   +-- start-lume-pipeline.bat   # UPDATED
|   +-- start-mocopi.bat          # UPDATED
+-- tools\
|   +-- nssm.exe                  # Third-party
+-- logs\
+-- config\
    +-- lume-k11.json             # NEW

Code changes summary:
- 0 lines changed in existing Python publishers
- 0 lines changed in existing 10 Unity C# components
- 0 lines changed in existing compute shaders
- ~1 line added to lume_packet_inspector.py (LUMM magic)
- ~200 lines NEW: mocopi_bridge.py
- ~120 lines NEW: LumeMocopiReceiver.cs
- ~100 lines NEW: install-services.ps1
- ~80 lines NEW: health-check.ps1
- ~80 lines NEW: LummReceiver.swift (MotionMix iOS)
- ~50 lines NEW: tests, firewall rules, config

---

Execution Waves

### Wave 0: Day 1 Bootstrap
1. K11 first-boot (K11-FIRST-BOOT.md steps 1-5)
2. Run k11-bootstrap.ps1 (Git, Python 3.12, Unity Hub)
3. Git clone repo to K11
4. pip install numpy
5. Run start-lume-pipeline.bat with synthetic publishers
6. Verify UDP traffic from Mac1 via Tailscale

Kill criterion: K11 can't run Python or Tailscale can't reach K11.

### Wave 1: Day 2 -- Femto Bolt
7. Connect Bolt to K11 USB-C
8. Install + verify Orbbec Viewer
9. Install pyorbbecsdk
10. Run pointcloud_pub.py --raw-depth with real Bolt
11. Caliper-verify K11 + Bolt dimensions

Kill criterion: pyorbbecsdk can't enumerate Bolt on Windows.

### Wave 2: Day 2-3 -- Unity on K11
13. Install Unity 6000.3.2f1 on K11
14. Build Unity Player Windows x86_64
15. Run with synthetic depth (verify compute shaders work on Vulkan)
16. Run with real Bolt depth
17. Run with real UMA-8 audio

Kill criterion: Compute shaders fail on Radeon 780M.

### Wave 3: Day 3 -- NSSM + Service Management
19. Download NSSM
20. Write + run install-services.ps1
22. Write firewall-rules.ps1
23. Register services
24. Reboot-verify auto-start
25. Write health-check.ps1
26. Register Unity in Task Scheduler

### Wave 4: Day 4 -- LUMM + mocopi Bridge (parallel with Wave 3)
27. Write LUMM spec
28-31. Write mocopi_bridge.py (Sony decoder + OSC fallback + LUMM publisher)
32. Update packet inspector
33. Write tests
34-35. Test on K11 with Sony PC app + phone fallback

Kill criterion: Sony binary protocol parsing fails. Fallback: phone-OSC-only mode.

### Wave 5: Day 4-5 -- Unity mocopi
36. Write LumeMocopiReceiver.cs
37-40. Wire into Auto-Wire, F12 panel, shader globals
41. Rebuild Unity Player

### Wave 6: Day 5 -- MotionMix iOS
42. Write LummReceiver.swift
43. Add settings toggle
44. Wire to MocopiFeatureExtractor
45. End-to-end test: K11 -> Tailscale -> iPhone

### Wave 7: Day 5-6 -- Production Hardening
47. Promote bridge to NSSM
48. 30-min sustained load test
49. Pod assembly test
50-51. Update docs + runbook
52. Cold-boot end-to-end dry run

---

Risk Summary

---

New Code to Write (in priority order)

1. mocopi_bridge.py (~200 lines) -- the only entirely new Python publisher
2. LumeMocopiReceiver.cs (~120 lines) -- Unity LUMM consumer
3. install-services.ps1 (~100 lines) -- NSSM service registration
4. health-check.ps1 (~80 lines) -- Windows diagnostic tool
5. LummReceiver.swift (~80 lines) -- MotionMix iOS LUMM consumer
6. firewall-rules.ps1 (~20 lines) -- UDP port allow rules
7. test_mocopi_bridge.py (~150 lines) -- Bridge test suite
8. LUMM section in lume_wire_format.md (~40 lines) -- Spec doc

Total new code: ~790 lines across 8 files.
Total unchanged existing code: ~3,661 lines (2,561 C# + 1,100 Python).