# raphiiko/oyasumivr architecture

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

- Interactive diagram: https://gitdiagram.com/raphiiko/oyasumivr
- Repository: https://github.com/raphiiko/oyasumivr

## Overview

##### Main Components
- Core Backend (src-core): This is the central integration point that contains many of the commands and services (e.g., handling HTTP, gRPC, hardware integrations, OS interactions, and telemetry). It also references Tauri configuration, so it may work as a bridge to desktop application frameworks.
- Elevated Sidecar (src-elevated-sidecar): A Rust-based module designed to perform privileged operations that cannot run in the normal user-space environment.
- Overlay Sidecar (src-overlay-sidecar & src-overlay-ui): Implemented partly in C# (for the service) and with a separate UI (likely Svelte-based) that manages overlay displays and interactions.
- MDNS Sidecar (src-mdns-sidecar): A C# project that handles mDNS (multicast DNS) service discovery; its purpose is to facilitate local network discovery or inter-process communication.
- gRPC-Web Client (src-grpc-web-client): Contains generated gRPC client code (using proto files like elevated-sidecar.proto, overlay-sidecar.proto, and oyasumi-core.proto) to allow web-based components to interact with backend services.
- Main UI (src-ui): An Angular-based (and possibly extended by other frontend technologies) application that presents a dashboard and settings, with extensive sub-components for controls, notifications, automations, and integrations.
- Shared Libraries (src-shared-rust, src-shared-ts): These provide common utilities and abstractions across the Rust and TypeScript codebases.

##### Relationships and Flows
– The Elevated Sidecar, MDNS Sidecar, and Overlay Sidecar should be depicted as independent services that the core invokes as needed.
– The gRPC-Web Client acts as a bridge between the browser (or main UI) and the backend services.
– The main UI (src-ui) pulls data and sends commands (likely over REST, websockets, or via a gRPC-Web interface) to the backend.
– External build and integration scripts (in the scripts and .run directories) support deployment and integration with external services (e.g., Steam integrations are visible from the scripts/steam directory).

##### Architectural Patterns and Design Principles
– The project follows a microservice or sidecar pattern (each service has a dedicated responsibility, e.g., elevated operations, overlay management, mDNS discovery).
– There is a clear separation between the frontend (Angular UI, Svelte overlay UI) and backend (Rust, C# services).
– Communication is standardized through gRPC and shared protocol files (in the proto folder) and possibly via IPC services (see src-core/src/utils/sidecar_manager.rs and IPC manager files in the C# projects).
– Shared modules (e.g., libraries in src-shared-rust and src-shared-ts) help enforce code reuse and consistency across different parts of the system.

##### Detail Without Overcomplicating
– The goal is to show how the user interface, core business logic, and various sidecar services communicate and collaborate.
– Include as many of the discrete components as possible (for example, splitting out “Overlay Service” from “Overlay UI,” and distinguishing between network discovery, privileged operations, and communications) to provide a complete architectural view.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Services
    subgraph "Frontend Services"
        UI["Main Dashboard UI (src-ui)"]:::frontend
        OverlayUI["Overlay UI (src-overlay-ui)"]:::frontend
    end

    %% Bridge for communication between frontend and backend
    subgraph "Bridge"
        GRPCWeb["gRPC-Web Client (src-grpc-web-client)"]:::bridge
    end

    %% Backend Services
    subgraph "Backend Services"
        Core["Core Engine (src-core)"]:::backend
        Elevated["Elevated Sidecar (src-elevated-sidecar)"]:::backend
        Overlay["Overlay Service (src-overlay-sidecar)"]:::backend
        MDNS["MDNS Sidecar (src-mdns-sidecar)"]:::backend
    end

    %% Shared Libraries
    subgraph "Shared Libraries"
        SharedRust["Shared Library Rust (src-shared-rust)"]:::shared
        SharedTS["Shared Library TS (src-shared-ts)"]:::shared
    end

    %% Connections between services
    UI -->|"calls"| GRPCWeb
    OverlayUI -->|"calls"| GRPCWeb
    GRPCWeb -->|"communicates"| Core

    Core -->|"invokes"| Elevated
    Core -->|"invokes"| Overlay
    Core -->|"invokes"| MDNS

    %% Shared library usage (dashed lines)
    Core --- SharedRust
    Elevated --- SharedRust
    Overlay --- SharedRust
    MDNS --- SharedRust

    UI --- SharedTS
    OverlayUI --- SharedTS
    GRPCWeb --- SharedTS

    %% Click Events
    click UI "https://github.com/raphiiko/oyasumivr/tree/develop/src-ui"
    click OverlayUI "https://github.com/raphiiko/oyasumivr/tree/develop/src-overlay-ui"
    click GRPCWeb "https://github.com/raphiiko/oyasumivr/tree/develop/src-grpc-web-client"
    click Core "https://github.com/raphiiko/oyasumivr/tree/develop/src-core"
    click Elevated "https://github.com/raphiiko/oyasumivr/tree/develop/src-elevated-sidecar"
    click Overlay "https://github.com/raphiiko/oyasumivr/tree/develop/src-overlay-sidecar"
    click MDNS "https://github.com/raphiiko/oyasumivr/tree/develop/src-mdns-sidecar"
    click SharedRust "https://github.com/raphiiko/oyasumivr/tree/develop/src-shared-rust"
    click SharedTS "https://github.com/raphiiko/oyasumivr/tree/develop/src-shared-ts"

    %% Styles
    classDef backend fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef frontend fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef bridge fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef shared fill:#d4edda,stroke:#155724,stroke-width:2px;
```
