# alvr-org/alvr architecture

> Architecture diagram of the GitHub repository alvr-org/alvr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alvr-org/alvr
- Repository: https://github.com/alvr-org/alvr

## Overview

##### Main components
- Server (PC) Side:
- Server Core (alvr/server_core): Handles streaming logic, video encoding/decoding, connection handling, logging, and statistics.
- Server IO (alvr/server_io): Manages firewall rules, OpenVR integration, and parts of the network interface.
- Server OpenVR (alvr/server_openvr): Contains C++ code for OpenVR integration and low-level interfacing with VR hardware (includes platform-specific code for Windows, Linux, macOS).
- Dashboard (alvr/dashboard): Provides a graphical user interface for installation, debugging, log viewing, and server configuration.
- Filesystem, Events, and Packets (alvr/filesystem, alvr/events, alvr/packets): Handle supportive tasks such as file management, input events, and data representations.
- Network Sockets (alvr/sockets): Implements the communication protocols (TCP/UDP) used to send/receive streaming data between the PC and the headset.
- Client (Headset) Side:
- Client Core (alvr/client_core): Acts as the core for client-side operations (e.g., handling decoded audio/video streams, managing connection state, logging, etc.).
- Client OpenXR (alvr/client_openxr): Manages integration with OpenXR – ensuring compatibility with various VR headsets.
- Audio and Graphics (alvr/audio, alvr/graphics): Provide platform-specific implementations for processing audio and rendering video streams.
- VR Compositor Wrapper (alvr/vrcompositor_wrapper): Wraps VR compositors to inject or manage streaming contexts.
- Cross-Cutting/Common Modules:
- Common (alvr/common): Shared libraries for logging, versioning, and general-purpose utilities.
- ADB (alvr/adb): Likely handles communication for Android-based headsets.
- Vulkan Layer (alvr/vulkan_layer): Implements a Vulkan intercept layer for capturing or modifying graphics calls, with associated cross-platform support.
- XTask (alvr/xtask): Contains helper scripts and tasks for building, packaging, and deployment.
- Other utility modules like session management (alvr/session) and system info (alvr/system_info).

##### Relationships and Interactions
- The Server Core modules communicate with the Client Core via the networking layer (sockets), sending encoded video, decoded audio, and control signals.
- The Dashboard (server side) interfaces with the Server Core to provide real-time insights, configuration options, and logging outputs.
- Platform-specific implementations (such as those found in server_openvr, client_openxr, audio, and graphics modules) connect with respective OS-level or VR runtime APIs.
- The Vulkan Layer intercepts Vulkan API calls on supported platforms, acting as an integration point between the system’s graphical output and VR headset rendering.
- Common utilities and shared protocols (alvr/common, alvr/packets) ensure consistent data structures and error/log management across different modules.
- The ADB and other xtask scripts ensure that deployment and build automation work seamlessly across the diverse components of the project.

##### Architectural Patterns and Principles
- Modularity and Separation of Concerns: Each directory addresses a distinct area (networking, audio, video, VR API integration) ensuring that each module is isolated and testable.
- Cross-Platform Abstractions: Many modules have platform-specific implementations (Windows, Linux, Android) as seen in folders like alvr/audio (linux.rs, windows.rs) and server_openvr (multiple platform directories).
- Client-Server Architecture: There is a clear division between the streaming server on the PC and the client on the VR headset, with an explicit network communication layer.
- Use of Both Rust and C++: Most business logic is implemented in Rust (as seen by extensive use of Cargo.toml files), but low-level VR interfacing and performance-critical components (like in server_openvr) are implemented in C++.

##### Relevant Technologies and Frameworks
- Rust for core modules, ensuring safety and concurrency.
- C++ for performance-critical and platform-specific VR interfacing.
- Use of Vulkan and OpenXR/OpenVR APIs for graphics and VR interactions.
- Networking libraries and protocols (part of the sockets modules) for real-time streaming.

- Annotations for architectural patterns (e.g., “modular”, “layered”, “platform adaptations”) and note any bridging modules like common utilities shared across server and client.
- Detail specific interactions, such as “Dashboard configures Server Core” or “Client Core communicates video/audio streams over sockets”.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% PC Side Components
    subgraph "PC Side"
        SC["Server Core"]:::server
        SIO["Server IO"]:::server
        SO["Server OpenVR"]:::server
        DB["Dashboard UI"]:::ui
        FS["Filesystem Support"]:::server
        EM["Events Manager"]:::server
        PM["Packets Module"]:::server
        NS["Network Sockets"]:::server
    end

    %% Headset Side Components
    subgraph "Headset Side"
        CC["Client Core"]:::client
        CX["Client OpenXR"]:::client
        AM["Audio Module"]:::client
        GM["Graphics Module"]:::client
        VC["VR Compositor Wrapper"]:::client
    end

    %% Common Modules
    subgraph "Common Modules"
        COM["Common Utilities"]:::common
        ADB["ADB Communication"]:::common
        VL["Vulkan Layer Integration"]:::common
        XT["XTask"]:::common
        SM["Session Management"]:::common
        SI["System Information"]:::common
    end

    %% Relationships and Data Flows
    DB -->|"configures"| SC
    SC -->|"invokes"| SIO
    SC -->|"invokes"| SO
    SC -->|"handles"| FS
    SC -->|"logsTo"| EM
    SC -->|"encapsulates"| PM
    SC -->|"streamsVia"| NS
    SIO -->|"triggers"| EM
    SIO -->|"communicatesWith"| NS
    SO -->|"integratesWithVR"| SC

    NS -->|"sendsStreamsTo"| CC
    CC -->|"receivesStreamsVia"| NS
    CC -->|"invokes"| CX
    CX -->|"drivesAudio"| AM
    CX -->|"drivesGraphics"| GM
    CX -->|"integratesWith"| VC

    %% Integration with Common Modules
    SC -.-> COM
    DB -.-> COM
    NS -.-> COM
    CC -.-> COM
    VC -.-> COM

    %% Platform Specific and Utility Interactions
    CC -.-> ADB
    GM -.-> VL
    SC -.-> XT
    CC -.-> XT
    SC -.-> SM
    CC -.-> SM
    SC -.-> SI
    CC -.-> SI

    %% Click Events for Components
    click SC "https://github.com/alvr-org/alvr/tree/master/alvr/server_core"
    click SIO "https://github.com/alvr-org/alvr/tree/master/alvr/server_io"
    click SO "https://github.com/alvr-org/alvr/tree/master/alvr/server_openvr"
    click DB "https://github.com/alvr-org/alvr/tree/master/alvr/dashboard"
    click FS "https://github.com/alvr-org/alvr/tree/master/alvr/filesystem"
    click EM "https://github.com/alvr-org/alvr/tree/master/alvr/events"
    click PM "https://github.com/alvr-org/alvr/tree/master/alvr/packets"
    click NS "https://github.com/alvr-org/alvr/tree/master/alvr/sockets"
    click CC "https://github.com/alvr-org/alvr/tree/master/alvr/client_core"
    click CX "https://github.com/alvr-org/alvr/tree/master/alvr/client_openxr"
    click AM "https://github.com/alvr-org/alvr/tree/master/alvr/audio"
    click GM "https://github.com/alvr-org/alvr/tree/master/alvr/graphics"
    click VC "https://github.com/alvr-org/alvr/tree/master/alvr/vrcompositor_wrapper"
    click COM "https://github.com/alvr-org/alvr/tree/master/alvr/common"
    click ADB "https://github.com/alvr-org/alvr/tree/master/alvr/adb"
    click VL "https://github.com/alvr-org/alvr/tree/master/alvr/vulkan_layer"
    click XT "https://github.com/alvr-org/alvr/tree/master/alvr/xtask"
    click SM "https://github.com/alvr-org/alvr/tree/master/alvr/session"
    click SI "https://github.com/alvr-org/alvr/tree/master/alvr/system_info"

    %% Styles for Components
    classDef server fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef client fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef common fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef ui fill:#f8d7da,stroke:#721c24,stroke-width:2px;
```
