Streaming Path: Service Roles Reference
Overview
This document describes every service involved when a user browses to hydraheadwebstream and starts a browser stream. Services are grouped by their role in the streaming path.
Orchestration & UI Data
hydraheadwebstream
- Role: Entry point — browser UI that lets users select an experience and district, then orchestrates the streaming session
- URL: http://46.225.210.188
- Health:
/health - Depends on: hydradistrict, hydraexperiencelibrary, hydracluster, hydrabody, hydraneckwebrtc
- Key behavior: Serves a web page where users pick an experience and district from dropdowns, then click "Start" to begin streaming. Coordinates with hydracluster to find an available body, then creates a WebRTC session via hydraneckwebrtc.
hydradistrict
- Role: Provides the district list for the UI dropdown
- URL: https://hydradistrict.experiencenet.com
- Health:
/api/v1/health - Key endpoints:
GET /api/v1/districts— returns list of districts with names and center IPs
hydraexperiencelibrary
- Role: Provides the experience list for the UI
- URL: https://hydraexperiencelibrary.experiencenet.com
- Health:
/api/v1/health - Key endpoints:
GET /api/v1/experiences— returns available experiences with metadata
hydracluster
- Role: Finds an available body (render node) in the selected district
- URL: https://hydracluster.experiencenet.com
- Health:
/api/v1/health - Config:
~/.hydracluster/config.yaml, nodes in~/.hydracluster/nodes.yaml - Key behavior: Receives a request for a body in a given district, checks node availability, returns a body assignment. Uses hydraclusterapi for shared types.
Stream Setup & Relay
hydrabody
- Role: Agent running on each render node — launches the UE app via Sunshine
- Not centrally reachable (runs on individual render nodes)
- Depends on: go-sunshine
- Key behavior: Receives instructions from hydracluster, uses go-sunshine SDK to register the UE application with Sunshine, then launches it. Sends heartbeats to hydrabodystatus with GPU metrics and stream session data.
go-sunshine
- Role: Go SDK for the Sunshine REST API
- Type: Library (imported by hydrabody)
- Key behavior: Wraps Sunshine's REST API for app registration, session management, and PIN pairing.
hydraneckwebrtc
- Role: Creates WebRTC sessions, spawns moonlight-web-stream processes, proxies video stream to browser
- URL: https://hydraneckwebrtc.experiencenet.com
- Health:
/health - Key endpoints:
POST /api/v1/sessions(create),GET /api/v1/sessions(list),DELETE /api/v1/sessions/<id>(destroy) - Key behavior: When a session is created, spawns a moonlight-web-stream subprocess that connects to Sunshine on the body. The video is proxied to the browser via WebRTC. Also handles mic relay for audio.
Audio
hydravoice
- Role: Browser mic to UE app audio pipeline
- Not centrally reachable (runs on render nodes)
- Key behavior: Receives RTP/UDP audio from hydraneckwebrtc's mic relay on port 47995, decodes via ffmpeg, routes through VB-Cable virtual audio device into the UE application.
Network
hydraguard
- Role: WireGuard mesh network carrying all streaming traffic
- URL: https://hydraguard.experiencenet.com
- Health:
/api/v1/health - Hub: 89.167.57.232, WireGuard port 51820/udp
- Key behavior: All traffic between the datacenter and edge venues flows through WireGuard tunnels managed by hydraguard. This includes video streams, control plane traffic, and heartbeats.
Shared Protocol Types
hydraclusterapi
- Role: Defines shared types: BodyConfig, StreamStatus, heartbeat structures
- Type: Library (imported by hydracluster and hydrabody)
- Key types:
BodyConfig,StreamStatus,Heartbeat,NodeConfig
Deployment & Provisioning
hydranode
- Role: Universal node agent that provisions hydrabody and other services on render nodes
- Not centrally reachable (runs on render nodes)
- Depends on: hydracluster (fetches config)
- Key behavior: Runs on every render node, pulls configuration from hydracluster, installs and manages hydrabody and other required services.
hydramirror
- Role: Distributed file mirror serving experience executables to bodies at edge venues
- Not centrally reachable (runs at edge)
- Key behavior: Caches and distributes large UE application binaries so bodies at edge venues can launch experiences without downloading from the central server.
hydrareverseproxy
- Role: TLS-terminating reverse proxy — HTTPS frontend for management services
- Key behavior: Handles TLS termination and routing for hydradistrict, hydraexperiencelibrary, and other *.experiencenet.com services.
Native Kiosk Path
hydrahead
- Role: Head device management — stores stream configurations per kiosk, provides reverse proxy for browser streams
- Key behavior: Each kiosk head device has a stream config (experience, district, stream URL). hydrahead manages these configs and provides them to hydraheadwindows agents.
hydraheadwindows
- Role: Windows kiosk agent — Moonlight client that auto-pairs with Sunshine, runs fullscreen 1080p60
- Key behavior: Runs on Windows kiosk machines, polls hydrahead for stream config, auto-pairs with Sunshine via PIN (using WTS session), launches Moonlight in fullscreen at 1080p60/150Mbps.
Shared Libraries
hydraapi
- Role: Standard API types — health responses, error types, SSE events, dependency introspection
- Type: Library
- Used by: Most services for consistent API response formats
hydraauth
- Role: Auth library — bearer token and session cookie middleware
- Type: Library
- Used by: Services requiring authentication
hydraserve
- Role: Autocert HTTPS serving library
- Type: Library
- Used by: Services that need automatic Let's Encrypt certificates
hydrawebcomponents
- Role: Shared web UI components — dark theme layout, login page, template renderer
- Type: Library
- Used by: Services with web dashboards
hydramonitor
- Role: SSE monitoring library — event bus, pub/sub, heartbeat infrastructure
- Type: Library
- Used by: Services that publish or subscribe to monitoring events
hydrarelease
- Role: Release server + pkg/updater for auto-updates
- URL: https://releases.experiencenet.com
- Type: Service + Library
- Used by: All services (via pkg/updater for 6-hourly auto-update checks)
Observability
hydrabodystatus
- Role: Body telemetry dashboard — receives rich heartbeats from hydrabody
- URL: https://hydrabodystatus.experiencenet.com
- Health:
/api/v1/health - Key endpoints:
GET /api/v1/bodies(admin token required) — returns per-body data including stream_status, stream_sessions[], gpu_temp, gpu_utilization, provider_status - Key behavior: Aggregates heartbeat data from all bodies. hydrastreamingmonitor consumes its API to show which bodies are actively streaming, GPU health, and session counts.
hydranps
- Role: Post-session NPS (Net Promoter Score) ratings
- URL: https://hydranps.experiencenet.com
- Health:
/api/v1/health - Key behavior: After a streaming session ends, collects user satisfaction ratings.