Data model & schema#

The infra graph is 16 CockroachDB tables across these concerns: a spatial hierarchy, devices with their ports and pluggable optical transceivers, a power chain with A/B redundancy, physical cabling, cooling, and logical fabric links. A 17th table — audit_log — is operational rather than part of the graph (it records change-data-capture events; see Audit & CDC). The diagram below reflects the migrations in internal/schema/migrations exactly.

*Entity/relationship diagram of the 17-table schema*

Spatial hierarchy#

sites → floors → rack_rows → racks → rack_units → devices → ports. Each level references its parent; racks also carry a cooling_budget_watts, and devices carry watts and heat_watts so power and thermal rollups have real numbers.

Optical transceivers#

transceivers model the pluggable optic installed in a port (one per port, a 1:1 port_id reference), as a first-class entity rather than a string on the cable. Each carries form_factor (QSFP28, QSFP-DD, SFP+, OSFP…), speed_gbps, vendor, part_number, and wavelength_nm — so cabling and fabric can reason about the optic, and the inspector surfaces it on GetDevice / GetPort.

Power chain & A/B redundancy#

Power is a dependency chain: feeds → pdus → outlets → power_links → power_ports → devices. A feed has a side of A or B. A device whose power_ports are linked (via power_links) to both an A-side and a B-side feed is A/B-redundant and survives the loss of either feed; a device fed by only one side goes dark when that side trips. This is exactly what the PowerBlastRadius walk computes.

Power chain + A/B redundancy + a blast-radius walk (feed B-3 trips)

In the worked example from NARRATIVE.md, PowerBlastRadius{ source_ref: "feed:B-3" } returns R08 and R10 as dark (B-only) and R07 and R09 as protected (still live on their A feed, though now single-fed).

Cabling, cooling, and fabric#

cables are edges between two ports. Patch panels relay a path by having two ports the recursive trace passes through — that’s how TraceCablePath follows a logical link across physical hops.
crac_units serve a floor with a capacity_watts; rolled against device heat_watts and per-rack budgets, they yield ThermalHeadroom and hotspots.
fabric_links are logical leaf→spine uplinks with a util_pct, kept separate from physical cables so the cable-path trace is unaffected by fabric adjacency and an uplink can carry utilization independent of any one physical run.

Audit log#

audit_log is a standalone operational table (no FK into the graph) that records one row per observed mutation of a tracked table — event_type, before/after JSONB images, and the changefeed MVCC timestamp. It’s populated by CockroachDB change-data-capture; see Audit & CDC.