Partner Network Design

This document describes the standard network design used when opening a new district with a managed network partner (telco, ISP, or managed services provider). It maps the partner's responsibilities to HYDRA ExperienceNet components and serves as shared documentation between HYDRA and the partner.

Terminology Mapping

Network Topology

graph LR
    Internet((Internet))

    subgraph district["District Cloud Server\nManaged by HYDRA"]
        direction TB
        HUB["HydraGuard Hub\n10.10.0.1/24\nWireGuard :51820"]
        NECK["HydraNeck WebRTC\ncontroller + workers"]
    end

    Internet --- HUB & NECK

    subgraph partner_zone["Partner Managed Locations\nCan have local Body and Head networks (+SSID)\nCan be 100% HYDRA or shared with existing venue/office network"]
        direction TB

        subgraph site_a["Site A -- CIDR 10.101.0.0/20"]
            direction LR
            PE_A["Provider Edge Router\nVLAN trunk to WireGuard /26"]
            VLAN_A_BODY["Body VLAN\n10.101.1.0/24"]
            VLAN_A_HEAD["Head VLAN\n10.101.4.0/20"]
            BODY_A1["Body\n10.101.1.2"]
            BODY_A2["Body\n10.101.1.3"]
            AP_A["Access Point\nExperienceNet"]
            HEAD_A1["Head\n10.101.4.10"]
            HEAD_A2["Head\n10.101.4.11"]
            PE_A --- VLAN_A_BODY --- BODY_A1 & BODY_A2
            PE_A --- VLAN_A_HEAD --- AP_A
            VLAN_A_HEAD --- HEAD_A1 & HEAD_A2
            HEAD_A1 -. "local via firewall rule" .-> BODY_A1
        end

        subgraph site_b["Site B -- CIDR 10.102.0.0/20"]
            direction LR
            PE_B["Provider Edge Router"]
            BODY_B1["Body\n10.102.1.2"]
            BODY_B2["Body\n10.102.1.3"]
            HEAD_B1["Head\n10.102.4.10"]
            PE_B --- BODY_B1 & BODY_B2
            PE_B --- HEAD_B1
            HEAD_B1 -. "local via firewall rule" .-> BODY_B1
        end

        subgraph site_c["Site C -- CIDR 10.103.0.0/20"]
            direction LR
            PE_C["Provider Edge Router"]
            BODY_C1["Body\n10.103.1.2"]
            AP_C["Access Point\nExperienceNet"]
            HEAD_C1["Head\n10.103.4.10"]
            PE_C --- BODY_C1
            PE_C --- AP_C --- HEAD_C1
            HEAD_C1 -. "local via firewall rule" .-> BODY_C1
        end

        EXPAND["... can be expanded as required"]
    end

    HUB -- WireGuard --- PE_A & PE_B & PE_C
    HUB -. "WireGuard independent" .- BODY_A1 & BODY_A2 & BODY_B1 & BODY_B2 & BODY_C1

    subgraph hydra_zone["HYDRA Managed Locations"]
        direction TB

        subgraph site_d["Site D -- MikroTik NeckAir\nCIDR 10.0.50.0/24"]
            direction LR
            RTR_D["MikroTik Router"]
            BODY_D1["Body\n10.0.50.2"]
            BODY_D2["Body\n10.0.50.3"]
            HEAD_D1["Head\n10.0.50.10"]
            RTR_D --- BODY_D1 & BODY_D2
            RTR_D --- HEAD_D1
            HEAD_D1 -- LAN --- BODY_D1
        end

        subgraph site_e["Site E -- Omada\nCIDR 10.0.1.0/24"]
            direction LR
            RTR_E["Omada Controller"]
            BODY_E1["Body\n10.0.1.2"]
            AP_E["Access Point\nExperienceNet"]
            HEAD_E1["Head\n10.0.1.10"]
            RTR_E --- BODY_E1
            RTR_E --- AP_E --- HEAD_E1
            HEAD_E1 -- LAN --- BODY_E1
        end
    end

    HUB -- WireGuard --- RTR_D & RTR_E
    HUB -. "WireGuard independent" .- BODY_D1 & BODY_D2 & BODY_E1

    subgraph standalone["Standalone Bodies"]
        AIR1["Air Body\n10.10.100.1"]
        AIR2["Air Body\n10.10.100.2"]
    end
    HUB -. WireGuard .- AIR1 & AIR2

    subgraph remote["Remote Heads"]
        direction TB
        REMOTE_WIFI["Home WiFi"]
        REMOTE_5G["Public 5G"]
        BROWSER["Browser"]
    end
    HUB -- WireGuard --- REMOTE_WIFI & REMOTE_5G
    NECK -- WebRTC --- BROWSER

    subgraph partner_mgmt["Partner Management (out of scope)"]
        PDC["Partner Datacenter"]
    end
    PDC -. "Management VPN" .- PE_A & PE_B & PE_C

    classDef body fill:#1e40af,stroke:#3b82f6,color:#fff
    classDef head fill:#92400e,stroke:#f59e0b,color:#fff
    classDef partner fill:#065f46,stroke:#34d399,color:#fff
    classDef district_node fill:#312e81,stroke:#818cf8,color:#fff
    classDef remote_node fill:#92400e,stroke:#f59e0b,color:#fff
    classDef ap fill:#065f46,stroke:#10b981,color:#fff
    classDef vlan fill:#0f172a,stroke:#334155,color:#94a3b8

    class BODY_A1,BODY_A2,BODY_B1,BODY_B2,BODY_C1,BODY_D1,BODY_D2,BODY_E1,AIR1,AIR2 body
    class HEAD_A1,HEAD_A2,HEAD_B1,HEAD_C1,HEAD_D1,HEAD_E1 head
    class PE_A,PE_B,PE_C,PDC,RTR_D,RTR_E partner
    class HUB,NECK district_node
    class REMOTE_WIFI,REMOTE_5G,BROWSER remote_node
    class AP_A,AP_C,AP_E ap
    class VLAN_A_BODY,VLAN_A_HEAD vlan

Three Connection Layers

1. Partner Management VPN (out of scope)

All partner-managed locations typically maintain a VPN back to the partner's datacenter for remote management and support. This is entirely separate from the HYDRA streaming infrastructure and does not carry any HYDRA traffic.

2. Site-to-District WireGuard (partner-managed locations)

At partner-managed locations:

• The partner creates a WireGuard tunnel from the site provider edge router to the district server using a /26 trunk subnet
• HYDRA supplies the WireGuard peer profile (public key, allowed IPs, endpoint)
• The tunnel allows local Heads to reach the district server for remote Body access in case local Bodies fail or are saturated
• The partner configures firewall rules to allow Head VLAN to Body VLAN traffic locally

In HydraGuard, these are configured as venues with a partner guard type. The partner guard type generates a minimal WireGuard config without PostUp scripts (since the partner manages the router).

3. Body-to-District WireGuard (HYDRA-managed)

Regardless of site type, every Body independently establishes its own WireGuard tunnel to the district server:

• Managed by HYDRA, not the partner
• Provisioned automatically via HydraCluster calling the HydraGuard API
• Assigned addresses in the 10.10.100.x range (Air peers)
• Ensures Bodies are always reachable from the district, even if the site tunnel is down

This is the critical path for remote Heads: they connect to the district server via WireGuard and route through it to reach any Body in the mesh. Heads directly connected to the internet can also create their own WireGuard tunnel (on installation done by the HYDRA app), without needing a site gateway.

Responsibilities

What HYDRA Provides to the Partner

For each partner-managed location, HYDRA provides:

1. WireGuard peer profile -- public key, allowed IPs, endpoint hostname, persistent keepalive
2. VLAN/CIDR allocation -- per-site addressing (e.g., 10.10X.0.0/20 for management, 10.10X.4.0/20 for heads)
3. Body WireGuard configs -- Bodies at the site get their own configs (independent of site tunnel)
4. Streaming software -- Sunshine pre-installed on Bodies, HydraHead on Heads