Foundation

Infrastructure services — organizations, node orchestration, networking, and access control.

Components: HydraOrganization, HydraCluster, HydraNeck, HydraGuard

What You'll Have

After completing foundation setup, the pipeline has:

• Organizations — a customer (who commissions experiences) and an agency (who builds them)
• Nodes — physical devices enrolled in HydraCluster: render machines (bodies), kiosks/tablets/VR headsets (heads), each assigned to a venue
• Experiences — registered in ExperienceLibrary with targeting (which venues, which devices), ready to receive builds

See the Locations runbook for districts and venues setup.

HydraOrganization          HydraExperienceLibrary              HydraCluster
┌──────────────────┐      ┌───────────────────────────┐      ┌──────────────────────┐
│ visit-flanders   │      │ visit-flanders-main-exp   │      │ bxl1 / heysel        │
│   type: customer │─────→│   owner: visit-flanders   │─────→│   body-001 (render)  │
│                  │      │   agency: soulmade        │      │   body-002 (render)  │
│ soulmade         │      │   district: bxl1          │      │   head-001 (kiosk)   │
│   type: agency   │      │   venues: heysel, ad6     │      │   head-002 (tablet)  │
└──────────────────┘      └───────────────────────────┘      └──────────────────────┘

All of this exists before the first build. When a build arrives (upstream), it flows into this pre-configured topology. HydraNeck ensures bodies and heads within a venue can reach each other over the network.

Register Organizations

Register the customer and agency in HydraOrganization. This is a one-time setup step per customer, not repeated per build.

# Register the customer who commissions experiences
hydraorganization create --id visit-flanders --name "Visit Flanders" --type customer

# Register the agency who builds experiences
hydraorganization create --id soulmade --name "Soulmade" --type agency

What to Verify

hydraorganization list --json

SSE events emitted: organization.created

Enroll Nodes

Nodes are the physical devices that will run experiences. Each node enrolls itself with HydraCluster, declaring its district, venue, and role.

• A body is a render node — GPU machine that runs the Unreal Engine experience and streams via LarkXR
• A head is an interface device — kiosk, tablet, VR headset, or touchscreen that connects to a body's stream
• A device can be both body and head (standalone mode)

Nodes self-enroll by running the HydraNode agent, which heartbeats to HydraCluster. An operator approves them:

# List pending nodes
hydracluster nodes list --status pending

# Approve a node
hydracluster nodes approve body-001
hydracluster nodes approve head-001

HydraNeck ensures bodies and heads within a venue can reach each other over the network. Without the neck, bodies render frames but heads can't receive the stream.

What to Verify

# All nodes in the venue are approved and healthy
hydracluster nodes list --district bxl1 --venue heysel

SSE events emitted: node.enrolled, node.approved

Active components: HydraCluster, HydraNeck, HydraNode agents.

Register the Experience

Create the experience in HydraExperienceLibrary. This defines what will be deployed, who owns it, and where it goes — all before any build exists.

hydraexperiencelibrary create visit-flanders-main-experience \
  --label "Visit Flanders Main" \
  --customer visit-flanders \
  --agency soulmade \
  --release-project visit-flanders-main-experience \
  --district bxl1 \
  --venue heysel

The --customer and --agency are organization IDs from HydraOrganization. The --release-project links to a HydraRelease project (which may not have any builds yet). The --district and --venue target where the experience will be deployed.

This is also when you can start on landing pages, solution design, and stakeholder expectations — the experience record is the anchor for all of that.

Targeting

ExperienceLibrary reads the available topology from HydraVenues and lets you target:

Districts and venues must exist in HydraVenues and be active before they can be targeted. ExperienceLibrary validates this before accepting targeting changes. Targeting is geographic — by district and venue, not by organization.

What to Verify

hydraexperiencelibrary get visit-flanders-main-experience --json
hydraexperiencelibrary status

SSE events emitted: experience.created

Active components: HydraExperienceLibrary, HydraOrganization (read), HydraVenues (read), HydraCluster (read).