Skip to main content

ADR-015: Smart Process Architecture for Overlay Management

Status​

Accepted

Context​

As we build out the VR overlay system, we need a robust architecture for managing multiple overlay processes. This includes considerations for:

  • Process lifecycle management (spawn, kill, restart)
  • Crash isolation and recovery
  • Resource efficiency for lightweight overlays
  • Future browser integration with CEF

Decision​

We will implement a three-tier process architecture:

1. Dashboard Process (Core Manager)​

  • Role: Central control hub + OverlayProcessManager
  • Responsibilities:
    • Spawning and managing other overlay processes
    • Health monitoring via IPC heartbeats
    • Position lock/unlock coordination
    • Settings management
    • User interface for overlay control

2. Shared VR Process​

  • Role: Host for lightweight overlays
  • Overlays: Wrist-mounted tools, HUD elements, notifications
  • Benefits:
    • Reduced memory overhead
    • Faster spawn times
    • Shared GPU resources
    • Efficient for simple overlays

3. Isolated Browser Processes (Future - Sprint 9)​

  • Role: Individual CEF instances per browser overlay
  • Benefits:
    • Crash isolation (one tab crash doesn't affect others)
    • Security boundaries
    • Independent update cycles
    • Per-process resource limits

Implementation Details​

Process Communication​

  • Use existing IPC system with TypedChannel<OverlayCommand>
  • Commands include: Spawn, Kill, Restart, UpdatePosition, Lock/Unlock
  • Health monitoring via periodic heartbeat messages

Position Management UX​

  1. Dashboard has "Unlock Overlays" toggle button
  2. When unlocked, all overlays show grab handles
  3. Users position overlays with VR controllers
  4. Return to dashboard to lock positions
  5. Save/load position presets for sharing

Crash Recovery​

  • OverlayProcessManager monitors process health
  • Automatic restart on unexpected termination
  • Exponential backoff for repeated failures
  • Error reporting to dashboard UI

Consequences​

Positive​

  • Robust crash isolation prevents full system failures
  • Efficient resource usage for simple overlays
  • Clean separation of concerns
  • Extensible for future overlay types
  • Good user experience with position management

Negative​

  • Additional complexity in process coordination
  • IPC overhead for cross-process communication
  • More complex debugging across processes
  • Need to handle process spawn failures gracefully

Alternatives Considered​

  1. Single Process Architecture

    • Simpler but no crash isolation
    • One browser crash would kill entire VR experience

  2. All Isolated Processes

    • Maximum isolation but high resource usage
    • Slow spawn times for simple overlays

  3. Static Process Pool

    • Pre-spawn processes but wastes resources
    • Difficult to scale dynamically

References​

  • Sprint 8 Plan: Unified Overlay System
  • IPC Architecture (ADR-004)
  • CEF Browser Integration (ADR-003)

Date​

2025-07-10

Authors​

  • Claude (AI Assistant)
  • VR Creator Platform Team