Skip to main content

ADR-022: VROS Architecture

Status​

Proposed

Context​

The current VR dashboard implementation (vr_dashboard_with_process_manager) is a monolithic application that combines:

  • Dashboard UI rendering
  • Process management for overlays
  • VR context management
  • System configuration
  • Performance monitoring

This monolithic approach has several limitations:

  1. Tight Coupling: UI logic is intertwined with system management
  2. Limited Extensibility: Cannot easily replace or extend the dashboard
  3. Testing Difficulty: Hard to test UI independently from system functions
  4. Code Complexity: Single 2000+ line file with mixed responsibilities
  5. Reusability: Cannot reuse process management for other UIs

The VROP (VR Overlay Protocol) architecture introduces VROPClient as a generic plugin host for overlays. However, we need a system-level orchestrator to manage all VROPClient processes and provide system services.

Decision​

We will create VROS (VR Overlay Scheduler) as a system-level orchestrator that:

  1. Manages All VROPClient Processes: Including spawning dashboard as a VROPClient instance
  2. Provides System Services: Exposes process management, configuration, and monitoring via IPC
  3. Orchestrates Process Lifecycle: Handles spawning, monitoring, and cleanup of all overlays
  4. Maintains Single Instance: Ensures only one VROS runs per system

Key Architectural Choices:​

  1. VROS Does NOT Host Plugins: Unlike the initial "VROPHost" name suggested, VROS is purely an orchestrator:

    • Spawns VROPClient processes (including dashboard)
    • Provides services via IPC
    • Manages process lifecycle
    • Does not load or execute plugins directly

  2. Service-Oriented Architecture: All system functions exposed as services:

    • ProcessManagementService
    • ConfigurationService
    • MonitoringService
    • LayoutService
    • DebugService

  3. Dashboard as VROPClient: Dashboard runs as a VROPClient process to:

    • Maintain consistent plugin architecture
    • Enable alternative dashboard implementations
    • Provide proper process isolation
    • Allow dashboard hot-reload during development

Consequences​

Positive Consequences​

  1. Modularity: Clear separation between UI and system logic
  2. Extensibility: Can create alternative dashboards or extend functionality
  3. Testability: Can test dashboard UI and services independently
  4. Maintainability: Smaller, focused codebases
  5. Reusability: Services can be used by other applications
  6. Security: Better isolation between components
  7. Development: Parallel development of host and dashboard

Negative Consequences​

  1. Complexity: Additional architectural layer
  2. Performance: Small overhead from service indirection
  3. Deployment: Two binaries (VROS + VROPClient) instead of one
  4. Migration: Requires refactoring existing code
  5. Documentation: More concepts to document and teach

Neutral Consequences​

  1. Process Count: Same number of processes (dashboard + overlays)
  2. Resource Usage: Similar memory footprint when optimized
  3. Communication: IPC still required but now structured

Alternatives Considered​

1. Dashboard as Regular VROPClient Instance​

Pros:

  • Simpler architecture (one binary)
  • Consistent plugin model

Cons:

  • No elevated privileges for process management
  • Circular dependency (client managing other clients)
  • Security concerns with system access

Rejected because: The dashboard needs system-level access that regular plugins shouldn't have.

2. Monolithic Dashboard with VROP Support​

Pros:

  • Minimal changes to existing code
  • No additional processes

Cons:

  • Perpetuates tight coupling
  • Limits extensibility
  • Inconsistent with VROP philosophy

Rejected because: Doesn't solve the fundamental architecture problems.

3. Microservices Architecture​

Pros:

  • Maximum flexibility
  • Independent scaling
  • Technology agnostic

Cons:

  • Over-engineered for desktop application
  • Complex deployment
  • Higher resource usage

Rejected because: Too complex for a single-user desktop application.

Implementation Strategy​

  1. Phase 1: Extract service interfaces from monolithic dashboard
  2. Phase 2: Create dashboard plugin implementing UI logic
  3. Phase 3: Implement VROS with service providers
  4. Phase 4: Migrate configuration and test thoroughly

References​