feat: network interface visualization and connectivity

[ggfevans]

📋 Migrated from rackarr/rackarr#93
Originally created by @ggfevans on 2025-12-18

---

Epic: Network Interface Visualization & Connectivity

Visualize network interfaces on device types and track connections between devices.

Status

✅ Research complete — Spike #237 completed (PR #242). Implementation ready to begin.

Child Issues

Research (Complete)

• spike: Network interface visualization research #237 - spike: Network interface visualization research (PR docs: network interface visualization spike research (#237) #242)

Phase 1: Interface Display

• feat: expand InterfaceTemplate type and Zod schema #247 - feat: expand InterfaceTemplate type and Zod schema
• spike: port layout algorithm for high-density devices #248 - spike: port layout algorithm for high-density devices
• feat: PortIndicators SVG component #249 - feat: PortIndicators SVG component
• feat: integrate PortIndicators into RackDevice #250 - feat: integrate PortIndicators into RackDevice
• feat: port tooltips on hover #251 - feat: port tooltips on hover
• feat: port display in image mode #252 - feat: port display in image mode
• feat: export includes port indicators #253 - feat: export includes port indicators
• feat: port position validation for half-depth devices #254 - feat: port position validation for half-depth devices
• chore: performance baseline for port visualization #255 - chore: performance baseline for port visualization

Phase 2: Port Details

• feat: port details panel in EditPanel #256 - feat: port details panel in EditPanel
• feat: interface list editor in EditPanel #257 - feat: interface list editor in EditPanel
• feat: interface configuration in Add Device form #258 - feat: interface configuration in Add Device form
• feat: import device type from NetBox YAML #259 - feat: import device type from NetBox YAML
• chore: populate starter library with interface data #260 - chore: populate starter library with interface data

Phase 3: Cable Connections

• feat: cable data model and schema #261 - feat: cable data model and schema
• spike: cable path rendering algorithm #262 - spike: cable path rendering algorithm
• feat: connection creation workflow (desktop) #263 - feat: connection creation workflow (desktop)
• feat: connection creation workflow (mobile) #264 - feat: connection creation workflow (mobile)
• feat: cable details panel #265 - feat: cable details panel
• feat: cable hover path highlighting #266 - feat: cable hover path highlighting
• feat: external connection handling #267 - feat: external connection handling
• feat: extend undo/redo for interface and cable operations #268 - feat: extend undo/redo for interface and cable operations

Phase 4: Advanced Features (v1.0.0+)

• feat: patch panel pass-through visualization #269 - feat: patch panel pass-through visualization
• feat: power port and outlet visualization #270 - feat: power port and outlet visualization
• feat: console port visualization #271 - feat: console port visualization
• feat: multi-rack cable visualization #272 - feat: multi-rack cable visualization
• feat: export connections to CSV/JSON #273 - feat: export connections to CSV/JSON
• feat: NetBox API sync (bidirectional) #274 - feat: NetBox API sync (bidirectional)

Cross-Cutting

• feat: mobile UX for port interaction #275 - feat: mobile UX for port interaction
• feat: port type categorization (network/power/console) #276 - feat: port type categorization (network/power/console)

Key Decisions from Spike

1. Port Indicators: SVG circles on device faces, color-coded by type
2. High-Density: Group ports into badges when >24 ports
3. Click Handling: foreignObject overlays for reliable events
4. NetBox Compatibility: Use NetBox field names for interoperability
5. Progressive Disclosure: Overview → detail on hover/zoom/click

Technical Notes

Schema already supports interfaces array in DeviceType:

interfaces: z.array(InterfaceSchema).optional()

Interface schema includes:

• name: Port identifier
• type: Interface type (e.g., "1000base-t")
• mgmt_only: Management-only flag

Spike research produced:

• docs/research/spike-237-network-interface-visualization.md
• docs/research/prototype-port-indicators.svelte
• docs/research/netbox-interface-cable-schema.md

Acceptance Criteria

Phase 1

• Research and design complete (spike spike: Network interface visualization research #237)
• Device faces render interface port indicators
• Hovering a port shows interface name and type
• 48+ port devices render without performance issues
• Interfaces exported correctly in SVG/PDF

Phase 2

• Users can view/edit interfaces on device types
• NetBox YAML can be imported
• Starter library devices have interface data

Phase 3

• Connections persist in .Rackula.zip archives
• Connection lines/curves visible in rack view
• Invalid connections (type mismatch) show warning
• Connections exported to CSV include cable info

Phase 4

• Patch panels support pass-through tracing
• Power and console ports visualized
• Multi-rack cables supported
• NetBox sync functional

---

Updated 2025-12-29 after spike completion