# moonlight-os/helios architecture

> Architecture diagram of the GitHub repository moonlight-os/helios, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/moonlight-os/helios
- Repository: https://github.com/moonlight-os/helios

## Overview

Helios is a Moonlight-compatible streaming host. A client pairs and configures access, then starts a session that captures and encodes host video, handles input and peripherals, and delivers the stream over negotiated transport. The README also documents virtual displays, browser-based administration, file/clipboard permissions, camera and microphone uplinks, and recovery/update capabilities. The source index identifies principal implementation areas, but much of their runtime wiring was not excerpted; uncertain links are marked dashed rather than inferred as calls.

Main entry points: [`src/stream.cpp`](https://github.com/moonlight-os/helios/blob/main/src/stream.cpp) (Session orchestration), [`src/entry_handler.cpp`](https://github.com/moonlight-os/helios/blob/main/src/entry_handler.cpp) (HTTP entry handling), [`src/nvhttp.cpp`](https://github.com/moonlight-os/helios/blob/main/src/nvhttp.cpp) (Pairing and protocol), [`src/platform/windows/display_vram.cpp`](https://github.com/moonlight-os/helios/blob/main/src/platform/windows/display_vram.cpp) (Display capture)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Host control"]
  node_main["Host startup<br/>[main.cpp]"]
  node_config["Runtime configuration<br/>[config.h]"]
  node_web["Browser configuration<br/>[confighttp.cpp]"]
  node_entry["HTTP entry handling<br/>[entry_handler.cpp]"]
  node_files["File permissions<br/>[file_handler.cpp]"]
  node_network["Network services<br/>[network.cpp]"]
  node_pairing["Pairing and protocol<br/>[nvhttp.cpp]"]
end

subgraph group_session["Streaming session"]
  node_session["Session orchestration<br/>[stream.cpp]"]
  node_video["Video pipeline<br/>[video.cpp]"]
  node_nvenc["NVENC encoding<br/>[nvenc_base.cpp]"]
  node_input["Input handling<br/>[input.cpp]"]
  node_audio["Audio handling<br/>[audio.cpp]"]
  node_quic["QUIC transport<br/>[quic_transport.cpp]"]
  node_usb["USB forwarding<br/>[usb_backend.cpp]"]
  node_camera["Camera uplink<br/>[camera.cpp]"]
end

subgraph group_platform["Platform services"]
  node_capture["Display capture<br/>[display_vram.cpp]"]
  node_linux_topology["Linux display topology"]
  node_display["Display management<br/>[display_device.h]"]
end

subgraph group_support["Host integrations"]
  node_crypto["Cryptographic services<br/>[crypto.cpp]"]
  node_upnp["Port mapping<br/>[upnp.cpp]"]
  node_logging["Logging and telemetry<br/>[logging.cpp]"]
  node_updater["Signed updates<br/>[updater.cpp]"]
end

node_client(("Moonlight client"))
node_host_os["Host operating system"]

node_client -.->|"pairs and negotiates"| node_pairing
node_client -.->|"uses configuration"| node_web
node_main -->|"starts host"| node_entry
node_entry -.->|"uses network services"| node_network
node_entry -.->|"uses settings"| node_config
node_pairing -.->|"negotiates sessions"| node_session
node_session -.->|"captures frames"| node_capture
node_capture -.->|"supplies frames"| node_video
node_video -.->|"encodes video"| node_nvenc
node_session -.->|"handles client input"| node_input
node_session -.->|"streams audio"| node_audio
node_session -.->|"uses negotiated transport"| node_quic
node_session -.->|"forwards session USB"| node_usb
node_session -.->|"accepts camera uplink"| node_camera
node_session -.->|"enforces file access"| node_files
node_session -.->|"manages client displays"| node_display
node_linux_topology -->|"controls Sway outputs"| node_host_os
node_capture -.->|"captures host display"| node_host_os
node_pairing -.->|"authenticates clients"| node_crypto
node_network -.->|"maps network ports"| node_upnp
node_main -->|"initializes host logging"| node_logging
node_updater -.->|"applies signed releases"| node_host_os

click node_main "https://github.com/moonlight-os/helios/blob/main/src/main.cpp"
click node_config "https://github.com/moonlight-os/helios/blob/main/src/config.h"
click node_web "https://github.com/moonlight-os/helios/blob/main/src/confighttp.cpp"
click node_entry "https://github.com/moonlight-os/helios/blob/main/src/entry_handler.cpp"
click node_files "https://github.com/moonlight-os/helios/blob/main/src/file_handler.cpp"
click node_network "https://github.com/moonlight-os/helios/blob/main/src/network.cpp"
click node_pairing "https://github.com/moonlight-os/helios/blob/main/src/nvhttp.cpp"
click node_session "https://github.com/moonlight-os/helios/blob/main/src/stream.cpp"
click node_capture "https://github.com/moonlight-os/helios/blob/main/src/platform/windows/display_vram.cpp"
click node_linux_topology "https://github.com/moonlight-os/helios/blob/main/src/platform/linux/client_topology.cpp"
click node_display "https://github.com/moonlight-os/helios/blob/main/src/display_device.h"
click node_video "https://github.com/moonlight-os/helios/blob/main/src/video.cpp"
click node_nvenc "https://github.com/moonlight-os/helios/blob/main/src/nvenc/nvenc_base.cpp"
click node_input "https://github.com/moonlight-os/helios/blob/main/src/input.cpp"
click node_audio "https://github.com/moonlight-os/helios/blob/main/src/audio.cpp"
click node_quic "https://github.com/moonlight-os/helios/blob/main/src/quic_transport.cpp"
click node_usb "https://github.com/moonlight-os/helios/blob/main/src/usb_backend.cpp"
click node_camera "https://github.com/moonlight-os/helios/blob/main/src/platform/windows/camera.cpp"
click node_crypto "https://github.com/moonlight-os/helios/blob/main/src/crypto.cpp"
click node_upnp "https://github.com/moonlight-os/helios/blob/main/src/upnp.cpp"
click node_logging "https://github.com/moonlight-os/helios/blob/main/src/logging.cpp"
click node_updater "https://github.com/moonlight-os/helios/blob/main/src/updater.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_config,node_web,node_entry,node_files,node_network,node_pairing,node_client toneBlue
class node_session,node_video,node_nvenc,node_input,node_audio,node_quic,node_usb,node_camera toneAmber
class node_capture,node_linux_topology,node_display toneMint
class node_crypto,node_upnp,node_logging,node_updater toneRose
class node_host_os toneIndigo
```

## Components

### Host control

- [Host startup](https://github.com/moonlight-os/helios/blob/main/src/main.cpp): `src/main.cpp`
- [Runtime configuration](https://github.com/moonlight-os/helios/blob/main/src/config.h): `src/config.h`
- [Browser configuration](https://github.com/moonlight-os/helios/blob/main/src/confighttp.cpp): `src/confighttp.cpp`
- [HTTP entry handling](https://github.com/moonlight-os/helios/blob/main/src/entry_handler.cpp): `src/entry_handler.cpp`
- [File permissions](https://github.com/moonlight-os/helios/blob/main/src/file_handler.cpp): `src/file_handler.cpp`
- [Network services](https://github.com/moonlight-os/helios/blob/main/src/network.cpp): `src/network.cpp`
- [Pairing and protocol](https://github.com/moonlight-os/helios/blob/main/src/nvhttp.cpp): `src/nvhttp.cpp`

### Streaming session

- [Session orchestration](https://github.com/moonlight-os/helios/blob/main/src/stream.cpp): `src/stream.cpp`
- [Video pipeline](https://github.com/moonlight-os/helios/blob/main/src/video.cpp): `src/video.cpp`
- [NVENC encoding](https://github.com/moonlight-os/helios/blob/main/src/nvenc/nvenc_base.cpp): `src/nvenc/nvenc_base.cpp`
- [Input handling](https://github.com/moonlight-os/helios/blob/main/src/input.cpp): `src/input.cpp`
- [Audio handling](https://github.com/moonlight-os/helios/blob/main/src/audio.cpp): `src/audio.cpp`
- [QUIC transport](https://github.com/moonlight-os/helios/blob/main/src/quic_transport.cpp): `src/quic_transport.cpp`
- [USB forwarding](https://github.com/moonlight-os/helios/blob/main/src/usb_backend.cpp): `src/usb_backend.cpp`
- [Camera uplink](https://github.com/moonlight-os/helios/blob/main/src/platform/windows/camera.cpp): `src/platform/windows/camera.cpp`

### Platform services

- [Display capture](https://github.com/moonlight-os/helios/blob/main/src/platform/windows/display_vram.cpp): `src/platform/windows/display_vram.cpp`
- [Linux display topology](https://github.com/moonlight-os/helios/blob/main/src/platform/linux/client_topology.cpp): `src/platform/linux/client_topology.cpp`
- [Display management](https://github.com/moonlight-os/helios/blob/main/src/display_device.h): `src/display_device.h`

### Host integrations

- [Cryptographic services](https://github.com/moonlight-os/helios/blob/main/src/crypto.cpp): `src/crypto.cpp`
- [Port mapping](https://github.com/moonlight-os/helios/blob/main/src/upnp.cpp): `src/upnp.cpp`
- [Logging and telemetry](https://github.com/moonlight-os/helios/blob/main/src/logging.cpp): `src/logging.cpp`
- [Signed updates](https://github.com/moonlight-os/helios/blob/main/src/updater.cpp): `src/updater.cpp`

### Other components

- **Moonlight client**
- **Host operating system**

## Connections

- Moonlight client → Pairing and protocol: pairs and negotiates
- Moonlight client → Browser configuration: uses configuration
- Host startup → HTTP entry handling: starts host (evidence: `src/main.cpp`)
- HTTP entry handling → Network services: uses network services (evidence: `src/entry_handler.cpp`)
- HTTP entry handling → Runtime configuration: uses settings (evidence: `src/entry_handler.cpp`)
- Pairing and protocol → Session orchestration: negotiates sessions
- Session orchestration → Display capture: captures frames
- Display capture → Video pipeline: supplies frames (evidence: `src/platform/windows/display_vram.cpp`)
- Video pipeline → NVENC encoding: encodes video
- Session orchestration → Input handling: handles client input
- Session orchestration → Audio handling: streams audio
- Session orchestration → QUIC transport: uses negotiated transport
- Session orchestration → USB forwarding: forwards session USB
- Session orchestration → Camera uplink: accepts camera uplink
- Session orchestration → File permissions: enforces file access
- Session orchestration → Display management: manages client displays
- Linux display topology → Host operating system: controls Sway outputs (evidence: `src/platform/linux/client_topology.cpp`)
- Display capture → Host operating system: captures host display
- Pairing and protocol → Cryptographic services: authenticates clients
- Network services → Port mapping: maps network ports
- Host startup → Logging and telemetry: initializes host logging (evidence: `src/main.cpp`)
- Signed updates → Host operating system: applies signed releases
