# wheaney/decky-xrgaming architecture

> Architecture diagram of the GitHub repository wheaney/decky-xrgaming, 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/wheaney/decky-xrgaming
- Repository: https://github.com/wheaney/decky-xrgaming

## Overview

##### Main components
- Frontend/UI Layer: Represented by the “src” folder containing various TSX/TS files (e.g., QrButton.tsx, SupporterTierModal.tsx, tutorials.tsx, etc.). This component is responsible for the plugin’s UI in Decky Loader, and handles user interactions to change display modes and adjust settings.
- Backend/Service Layer: Found in “backend” (with Dockerfile and entrypoint.sh) and possibly “main.py”. This service handles business logic such as configuration management, IPC (note the “PyXRLinuxDriverIPC” file), and licensing for Supporter Tier features. It may also interact with external services (such as Ko-fi for payments) and perform device-specific actions.
- Plugin Configuration & Metadata: Files like “plugin.json”, “package.json”, and “rollup.config.js” indicate how the plugin is built, packaged, and loaded by Decky Loader.
- Integration Components: The project integrates with external dependencies like Breezy Desktop’s Vulkan implementation and the XRLinuxDriver. This creates an implicit component representing the external driver/hardware interface.
- Utility/Tooling: The “bin” directory (package, update_remote_binaries) and “defaults” directory show additional scripts to package and update binaries, which are essential during deployment and updates.

##### Relationships and interactions
- The Backend interacts with external hardware drivers or libraries (e.g., Breezy Vulkan and XRLinuxDriverIPC) to manage head-tracking, virtual display adjustments, and extended configuration features.
- The plugin sits within the Decky Loader ecosystem. Illustrate how the Decky Loader provides the hosting environment, with both the UI and the backend being loaded as part of the plugin infrastructure.
- Deployment pipeline – including Docker for sandboxing the backend – and any update mechanism orchestrated through the “bin/update_remote_binaries” script.

##### Architectural patterns and technology choices
- Frontend is likely built with a component-based pattern (React or similar framework), which handles modular UI components, state management (as seen from “stableState.ts”), and interactions.
- Backend services follow a containerized deployment (referencing the Dockerfile) and may adhere to a microservice or modular design, handling licensing and configuration via a defined API.
- The use of IPC in “PyXRLinuxDriverIPC” suggests decoupled components where the frontend communicates with low-level system interfaces.

##### Additional details
- That the “assets” folder contains tutorials and visual assets for the UI which might provide context during user interactions.
- Optionally, represent the build system and packaging (via “package.json”, “pnpm-lock.yaml”, “rollup.config.js”) which affect how the frontend and plugin are compiled and deployed.
- If necessary, add notes indicating that some IPC components are abstracted (referenced by PyXRLinuxDriverIPC and decky.pyi) to manage interactions between the plugin and the device’s display hardware.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Plugin Configuration & Metadata
    subgraph "Plugin Configuration & Metadata"
        P1["plugin.json"]:::config
        P2["package.json"]:::config
        P3["rollup.config.js"]:::config
    end

    %% Decky Loader Host (Plugin environment)
    D["Decky Loader Host"]:::decky

    %% Frontend/UI Layer
    F["XR Plugin UI"]:::frontend

    %% Backend Service Layer
    subgraph "Backend Service"
        B1["Dockerized Service (backend/)"]:::backend
        B2["Main Service Script (main.py)"]:::backend
    end

    %% External XR Drivers / Hardware Interface
    subgraph "XR Driver Integration"
        I1["PyXRLinuxDriverIPC (root)"]:::integration
        I2["PyXRLinuxDriverIPC (defaults)"]:::integration
    end

    %% Utility/Tooling
    U1["Utility & Tooling (bin/)"]:::utility

    %% Assets (Tutorials and Visuals)
    A1["Assets & Tutorials (assets/)"]:::assets

    %% Connections
    P1 -->|"configures"| D
    P2 -->|"configures"| D
    P3 -->|"configures"| D

    D -->|"hosts"| F
    D -->|"hosts"| B1
    D -->|"hosts"| B2

    F -->|"sendsAPICalls"| B1
    F -->|"sendsAPICalls"| B2

    B1 -->|"commands"| I1
    B2 -->|"commands"| I2

    B1 -->|"triggers"| U1
    B2 -->|"triggers"| U1

    F -->|"fetchesAssets"| A1

    %% Click Events
    click F "https://github.com/wheaney/decky-xrgaming/tree/main/src/"
    click B1 "https://github.com/wheaney/decky-xrgaming/tree/main/backend/"
    click B2 "https://github.com/wheaney/decky-xrgaming/blob/main/main.py"
    click P1 "https://github.com/wheaney/decky-xrgaming/blob/main/plugin.json"
    click P2 "https://github.com/wheaney/decky-xrgaming/blob/main/package.json"
    click P3 "https://github.com/wheaney/decky-xrgaming/blob/main/rollup.config.js"
    click I1 "https://github.com/wheaney/decky-xrgaming/tree/main/PyXRLinuxDriverIPC"
    click I2 "https://github.com/wheaney/decky-xrgaming/tree/main/defaults/PyXRLinuxDriverIPC"
    click U1 "https://github.com/wheaney/decky-xrgaming/tree/main/bin/"
    click A1 "https://github.com/wheaney/decky-xrgaming/tree/main/assets/"
    click D "https://github.com/wheaney/decky-xrgaming/blob/main/decky.pyi"

    %% Styles
    classDef decky fill:#ffcc00,stroke:#000,stroke-width:2px;
    classDef frontend fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef backend fill:#90ee90,stroke:#000,stroke-width:2px;
    classDef config fill:#f4a460,stroke:#000,stroke-width:2px;
    classDef integration fill:#dda0dd,stroke:#000,stroke-width:2px;
    classDef utility fill:#ffb6c1,stroke:#000,stroke-width:2px;
    classDef assets fill:#ffa07a,stroke:#000,stroke-width:2px;
```
