Network Topology

WAVE Synapse models your physical and logical network infrastructure as a graph of sites, network segments, and devices. This topology awareness enables intelligent routing decisions, VLAN-aware path validation, and interactive visualization.

Core Concepts

Sites

A site represents a physical location: a studio, data center, office, or remote venue. Sites are the top-level organizational unit for network topology.

Field	Description
name	Human-readable name (e.g., “New York Studio”)
address	Physical address
timezone	IANA timezone (e.g., “America/New_York”)
metadata	Arbitrary JSON for custom attributes

Network Segments

A network segment represents a VLAN, subnet, or logical network partition within a site. Segments define the broadcast domain boundaries that affect device discovery and signal routing.

Field	Description
name	Segment name (e.g., “Production VLAN 100”)
site_id	Which site this segment belongs to
vlan_id	VLAN tag number
subnet	CIDR notation (e.g., “10.0.1.0/24”)
gateway	Default gateway IP address
multicast_enabled	Whether multicast traffic is allowed (required for NDI/Dante)
ptp_enabled	Whether Precision Time Protocol is active (required for Dante)
igmp_snooping	Whether IGMP snooping is configured on the switches

Topology Graph

The topology graph combines sites, segments, and devices into a navigable visualization:

Managing Sites

Create a Site

const response = await fetch('/api/ncp/topology/sites', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${accessToken}`,
  },
  body: JSON.stringify({
    name: 'Los Angeles Broadcast Center',
    address: '100 Broadcast Way, Los Angeles, CA 90001',
    timezone: 'America/Los_Angeles',
    metadata: {
      building_code: 'LA-BC-01',
      floors: 3,
    },
  }),
});

List Sites

const response = await fetch('/api/ncp/topology/sites', {
  headers: { 'Authorization': `Bearer ${accessToken}` },
});
 
const { data: sites } = await response.json();

Update a Site

await fetch(`/api/ncp/topology/sites/${siteId}`, {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${accessToken}`,
  },
  body: JSON.stringify({
    name: 'LA Broadcast Center - Updated',
  }),
});

Managing Network Segments

Create a Network Segment

const response = await fetch('/api/ncp/topology/segments', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${accessToken}`,
  },
  body: JSON.stringify({
    site_id: 'site-uuid',
    name: 'Production Video VLAN',
    vlan_id: 100,
    subnet: '10.0.100.0/24',
    gateway: '10.0.100.1',
    multicast_enabled: true,
    ptp_enabled: false,
    igmp_snooping: true,
  }),
});

List Segments

const response = await fetch('/api/ncp/topology/segments', {
  headers: { 'Authorization': `Bearer ${accessToken}` },
});

Update a Segment

await fetch(`/api/ncp/topology/segments/${segmentId}`, {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${accessToken}`,
  },
  body: JSON.stringify({
    multicast_enabled: true,
    ptp_enabled: true,
  }),
});

Multicast, PTP, and IGMP

These three network features are critical for professional AV protocols:

Feature	Required By	Purpose
Multicast	NDI, Dante	Efficient one-to-many signal distribution without duplicating unicast streams
PTP (Precision Time Protocol)	Dante, AES67	Sub-microsecond clock synchronization across audio devices
IGMP Snooping	All multicast protocols	Switch-level filtering that prevents multicast flooding to ports that have not subscribed

When creating or updating a segment, set these flags to reflect the actual switch configuration. Synapse uses these flags during route validation to determine whether a proposed route is feasible on a given network segment.

Interactive Graph Visualization

The topology API returns a graph structure compatible with the @xyflow/react library for interactive visualization:

const response = await fetch('/api/ncp/topology', {
  headers: { 'Authorization': `Bearer ${accessToken}` },
});
 
const { data: graph } = await response.json();
// graph.nodes = TopologyNode[]
// graph.edges = TopologyEdge[]

Node Types

Type	Represents	Visual
site	Physical location	Building icon with site name
segment	Network VLAN/subnet	Network cloud with VLAN info
device	Individual device	Device icon with health badge

Edge Types

Type	Represents	Visual
membership	Device belongs to segment, or segment belongs to site	Solid line
route	Active signal route between devices	Dashed line with signal type label

The graph data includes position hints when available, but the frontend layout engine can reposition nodes for optimal visibility.

Segment Capacity

Track bandwidth utilization per segment:

interface SegmentCapacity {
  segment_id: string;
  total_bandwidth_mbps: number;
  used_bandwidth_mbps: number;
  remaining_bandwidth_mbps: number;
  utilization_percent: number;
}

High utilization (above 80%) on a segment may indicate that adding more routes could degrade quality for existing streams.

Reachability

Before creating a route between devices on different segments, Synapse checks reachability:

interface ReachabilityResult {
  reachable: boolean;
  requires_routing: boolean;  // true if devices are on different subnets
  hops: string[];             // intermediate network segments/routers
  estimated_latency_ms: number | null;
}

If requires_routing is true, the route will traverse a Layer 3 boundary, which may add latency and requires that inter-VLAN routing is configured on the network infrastructure.

Database Schema

ncp_sites

CREATE TABLE ncp_sites (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  organization_id UUID NOT NULL REFERENCES organizations(id),
  name TEXT NOT NULL,
  address TEXT,
  timezone TEXT,
  metadata JSONB DEFAULT '{}',
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

ncp_network_segments

CREATE TABLE ncp_network_segments (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  organization_id UUID NOT NULL REFERENCES organizations(id),
  site_id UUID REFERENCES ncp_sites(id),
  name TEXT NOT NULL,
  vlan_id INT,
  subnet CIDR,
  gateway INET,
  multicast_enabled BOOLEAN DEFAULT false,
  ptp_enabled BOOLEAN DEFAULT false,
  igmp_snooping BOOLEAN DEFAULT false,
  metadata JSONB DEFAULT '{}',
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

Both tables have RLS policies restricting access to organization members.