docs: network interface visualization spike research (#237) #242
Conversation
Spike research for adding network interface port visualization to Rackula. Deliverables: - Findings document with SVG rendering approach, data model design, UX pattern research, and implementation phase plan - SVG prototype demonstrating port indicator rendering - NetBox interface/cable schema research for compatibility Key findings: - Existing SVG architecture easily supports port indicators - NetBox schema provides solid foundation for interface types - Phase 1 (interface indicators) estimated at 2-3 days - Progressive disclosure essential for 48+ port devices Recommendation: Proceed with Phase 1 implementation Closes #237 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
📝 WalkthroughWalkthroughThree new research artifacts for network interface visualization in Spike Changes
Estimated Code Review Effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly Related Issues
Poem
Pre-merge checks✅ Passed checks (5 passed)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 9
📜 Review details
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (3)
docs/research/netbox-interface-cable-schema.mddocs/research/prototype-port-indicators.sveltedocs/research/spike-237-network-interface-visualization.md
🧰 Additional context used
📓 Path-based instructions (2)
**/*.{ts,tsx,js,svelte}
📄 CodeRabbit inference engine (CLAUDE.md)
Use TypeScript strict mode
Files:
docs/research/prototype-port-indicators.svelte
**/*.{css,svelte}
📄 CodeRabbit inference engine (CLAUDE.md)
Use CSS custom properties (design tokens) from
src/lib/styles/tokens.cssinstead of hardcoded CSS values
Files:
docs/research/prototype-port-indicators.svelte
🪛 LanguageTool
docs/research/spike-237-network-interface-visualization.md
[typographical] ~17-~17: If specifying a range, consider using an en dash instead of a hyphen.
Context: ... Phase 1 implementation is estimated at 2-3 days Recommendation: Proceed with ...
(HYPHEN_TO_EN)
[typographical] ~322-~322: If specifying a range, consider using an en dash instead of a hyphen.
Context: ...import ### Phase 3: Cable Connections (4-5 days) Goal: Visualize cables betwee...
(HYPHEN_TO_EN)
[grammar] ~347-~347: A determiner may be missing.
Context: ...vention | | Position at device bottom | Least interference with device label/image | ...
(THE_SUPERLATIVE)
docs/research/netbox-interface-cable-schema.md
[uncategorized] ~159-~159: Loose punctuation mark.
Context: ...tracing connections: - link_peers: Returns directly connected objects (imm...
(UNLIKELY_OPENING_PUNCTUATION)
[style] ~162-~162: To elevate your writing, try using an alternative expression here.
Context: ...return the same values. The distinction matters for complex paths involving patch panel...
(MATTERS_RELEVANT)
[typographical] ~406-~406: Two consecutive commas
Context: ...b-mini-a, usb-mini-b, usb-micro-a, usb-micro-b-molex-micro-fit-1x2, molex-micro-fit-2x2, molex-micro-fit...
(DOUBLE_PUNCTUATION)
[uncategorized] ~410-~410: Loose punctuation mark.
Context: ...-saf-d-grid-neutrik-powercon-20, neutrik-powercon-32, neutrik-powerco...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~428-~428: Possible missing comma found.
Context: ...munity/devicetype-library Organized by manufacturer with YAML files for each device model. ...
(AI_HYDRA_LEO_MISSING_COMMA)
[uncategorized] ~555-~555: Possible missing article found.
Context: ...rt model suggests: 1. Positioning is visual concept: Not core to NetBox's data mo...
(AI_HYDRA_LEO_MISSING_A)
[duplication] ~589-~589: Possible typo: you repeated a word.
Context: ...devicetype-library) - netbox-community/netbox - [NetBox Demo API](https://demo.netbox.dev/api/s...
(ENGLISH_WORD_REPEAT_RULE)
🪛 markdownlint-cli2 (0.18.1)
docs/research/spike-237-network-interface-visualization.md
29-29: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
294-294: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
315-315: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
322-322: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
330-330: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
389-389: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
398-398: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
405-405: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
411-411: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
docs/research/netbox-interface-cable-schema.md
57-57: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
62-62: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
68-68: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
78-78: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
82-82: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
86-86: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
91-91: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
97-97: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
100-100: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
103-103: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
107-107: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
115-115: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
128-128: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
140-140: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
165-165: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
261-261: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
426-426: Bare URL used
(MD034, no-bare-urls)
522-522: Bare URL used
(MD034, no-bare-urls)
579-579: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
587-587: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
592-592: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
598-598: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
602-602: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
606-606: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
715-715: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
🔇 Additional comments (1)
docs/research/netbox-interface-cable-schema.md (1)
614-714: Most impressive research and recommendations, excellent!The TypeScript type proposals are well-structured and align perfectly with NetBox's schema while adding sensible Rackula extensions like
position. The phased implementation strategy demonstrates sound technical planning.
| ### 5.1 Repository | ||
|
|
||
| NetBox device type definitions are maintained in the **netbox-community/devicetype-library** repository: | ||
| - https://github.com/netbox-community/devicetype-library |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Ah, a bare URL lurks in the shadows!
Consider wrapping this GitHub URL in proper markdown link syntax for improved formatting, my friend.
🔎 Proposed fix
-https://github.com/netbox-community/devicetype-library
+[GitHub: netbox-community/devicetype-library](https://github.com/netbox-community/devicetype-library)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - https://github.com/netbox-community/devicetype-library | |
| - [GitHub: netbox-community/devicetype-library](https://github.com/netbox-community/devicetype-library) |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
426-426: Bare URL used
(MD034, no-bare-urls)
🤖 Prompt for AI Agents
In docs/research/netbox-interface-cable-schema.md around line 426 there is a
bare URL; replace it with a markdown link (e.g.
[devicetype-library](https://github.com/netbox-community/devicetype-library)) so
the URL is rendered as a clickable, descriptive link in the documentation.
| ### 5.7 Import Automation | ||
|
|
||
| NetBox Community provides a Python import script: | ||
| - https://github.com/netbox-community/Device-Type-Library-Import |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Another bare URL discovered in the crypt!
This URL should also be converted to a proper markdown link for consistency.
🔎 Proposed fix
-- https://github.com/netbox-community/Device-Type-Library-Import
+- [Device-Type-Library-Import Tool](https://github.com/netbox-community/Device-Type-Library-Import)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - https://github.com/netbox-community/Device-Type-Library-Import | |
| - [Device-Type-Library-Import Tool](https://github.com/netbox-community/Device-Type-Library-Import) |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
522-522: Bare URL used
(MD034, no-bare-urls)
🤖 Prompt for AI Agents
In docs/research/netbox-interface-cable-schema.md around line 522, replace the
bare URL "https://github.com/netbox-community/Device-Type-Library-Import" with a
proper Markdown link; e.g., use descriptive link text such as [Device Type
Library Import](https://github.com/netbox-community/Device-Type-Library-Import)
so the URL is not left bare and matches the repo's link style in the document.
| const INTERFACE_COLORS: Record<InterfaceType, string> = { | ||
| '1000base-t': '#10b981', // Emerald - 1GbE | ||
| '10gbase-t': '#3b82f6', // Blue - 10GbE copper | ||
| '10gbase-x-sfpp': '#8b5cf6', // Purple - SFP+ | ||
| '25gbase-x-sfp28': '#f59e0b', // Amber - SFP28 | ||
| '40gbase-x-qsfpp': '#ef4444', // Red - QSFP+ | ||
| '100gbase-x-qsfp28': '#ec4899', // Pink - QSFP28 | ||
| }; |
There was a problem hiding this comment.
Ah, I detect the scent of hardcoded hex values in the night!
The INTERFACE_COLORS constant uses hardcoded color values, which violates the coding guidelines. These should reference CSS custom properties from src/lib/styles/tokens.css for consistency across the application.
As per coding guidelines, all color values should use design tokens.
🔎 Suggested approach
Since this is a research prototype, you have two options:
- Document the limitation:
// TODO: Replace with CSS custom properties from tokens.css in production
// These are hardcoded for prototype demonstration only
const INTERFACE_COLORS: Record<InterfaceType, string> = {- Use CSS variables:
const INTERFACE_COLORS: Record<InterfaceType, string> = {
'1000base-t': 'var(--color-emerald-500)',
'10gbase-t': 'var(--color-blue-500)',
// ... etc
};🤖 Prompt for AI Agents
In docs/research/prototype-port-indicators.svelte around lines 36 to 43, the
INTERFACE_COLORS map currently uses hardcoded hex values which violates the
design-token rule; replace each hex string with the appropriate CSS custom
property from src/lib/styles/tokens.css (e.g. 'var(--color-emerald-500)') or, if
this file must remain a prototype, add a clear TODO comment above the constant
indicating these are temporary hardcoded values and must be migrated to CSS
variables in production; ensure the mapping keys/types remain unchanged and
values are plain CSS variable strings.
| <circle | ||
| class="port-circle" | ||
| cx={x} | ||
| cy={y} | ||
| r={PORT_RADIUS} | ||
| fill={color} | ||
| stroke="rgba(0,0,0,0.3)" | ||
| stroke-width="0.5" | ||
| /> |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Inline SVG colour attributes detected, most curious!
While not technically CSS, the hardcoded stroke and fill colors in the SVG elements could be improved by using CSS classes that reference design tokens, ensuring consistency with the application's colour scheme.
🔎 Alternative approach
Move the stroke styling to CSS:
<circle
class="port-circle"
cx={x}
cy={y}
r={PORT_RADIUS}
fill={color}
- stroke="rgba(0,0,0,0.3)"
- stroke-width="0.5"
/>Add to CSS:
.port-circle {
stroke: var(--color-stroke-subtle, rgba(0, 0, 0, 0.3));
stroke-width: 0.5;
}Committable suggestion skipped: line range outside the PR's diff.
🤖 Prompt for AI Agents
In docs/research/prototype-port-indicators.svelte lines 123–131, the SVG circle
uses hardcoded inline stroke and stroke-width attributes (and a dynamic fill
binding) which prevents using centralised design tokens; remove the inline
stroke and stroke-width attributes from the <circle> element and instead define
them in the component CSS under the existing .port-circle rule using
design-token-backed CSS variables (e.g. --color-stroke-subtle and --port-fill)
and stroke-width; if the fill should also follow the design system, switch the
dynamic fill binding to a CSS variable or a class that maps to a design token,
otherwise keep the dynamic fill binding but ensure stroke values come from CSS.
| .port-click-target:hover { | ||
| background: rgba(255, 255, 255, 0.2); | ||
| } |
There was a problem hiding this comment.
Another hardcoded colour lurks in your stylesheet!
The hover background uses a hardcoded rgba(255, 255, 255, 0.2) value, which should be replaced with a CSS custom property from the design tokens for consistency.
As per coding guidelines, avoid hardcoded CSS values.
🔎 Suggested fix
.port-click-target:hover {
- background: rgba(255, 255, 255, 0.2);
+ background: var(--color-overlay-hover, rgba(255, 255, 255, 0.2));
}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| .port-click-target:hover { | |
| background: rgba(255, 255, 255, 0.2); | |
| } | |
| .port-click-target:hover { | |
| background: var(--color-overlay-hover, rgba(255, 255, 255, 0.2)); | |
| } |
🤖 Prompt for AI Agents
In docs/research/prototype-port-indicators.svelte around lines 262–264, the
hover rule uses a hardcoded rgba(255, 255, 255, 0.2); replace that hardcoded
colour with the project’s design token CSS custom property (e.g. the
white/overlay alpha token) — update the .port-click-target:hover background to
use var(--<appropriate-design-token>, rgba(255,255,255,0.2)) so it reads from
the design system while keeping the current value as a fallback.
| .port-count-text { | ||
| fill: white; | ||
| font-size: 6px; | ||
| font-weight: 600; | ||
| font-family: var(--font-mono, monospace); | ||
| text-shadow: 0 0.5px 1px rgba(0, 0, 0, 0.5); | ||
| } |
There was a problem hiding this comment.
More hardcoded colours discovered in the port count text!
This style rule contains hardcoded values that violate the coding guidelines:
- Line 284:
fill: white - Line 288:
text-shadow: 0 0.5px 1px rgba(0, 0, 0, 0.5)
These should reference CSS custom properties from the design tokens.
As per coding guidelines, use CSS custom properties instead of hardcoded values.
🔎 Suggested fix
.port-count-text {
- fill: white;
+ fill: var(--color-text-inverse, white);
font-size: 6px;
font-weight: 600;
font-family: var(--font-mono, monospace);
- text-shadow: 0 0.5px 1px rgba(0, 0, 0, 0.5);
+ text-shadow: 0 0.5px 1px var(--shadow-color-dark, rgba(0, 0, 0, 0.5));
}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| .port-count-text { | |
| fill: white; | |
| font-size: 6px; | |
| font-weight: 600; | |
| font-family: var(--font-mono, monospace); | |
| text-shadow: 0 0.5px 1px rgba(0, 0, 0, 0.5); | |
| } | |
| .port-count-text { | |
| fill: var(--color-text-inverse, white); | |
| font-size: 6px; | |
| font-weight: 600; | |
| font-family: var(--font-mono, monospace); | |
| text-shadow: 0 0.5px 1px var(--shadow-color-dark, rgba(0, 0, 0, 0.5)); | |
| } |
🤖 Prompt for AI Agents
In docs/research/prototype-port-indicators.svelte around lines 283–289, the
.port-count-text rule uses hardcoded colours (fill: white and text-shadow with
rgba(0,0,0,0.5)); replace those hardcoded values with the appropriate CSS custom
properties from the design tokens (e.g. var(--color-... ) for the fill and
var(--shadow-color-...) or a token representing overlay/disabled shadow for the
text-shadow color), provide sensible fallbacks if needed, and if the required
tokens don’t exist add them to the global design token file (:root) before using
them.
| ``` | ||
| <g class="rack-device" transform="translate(...)"> | ||
| 1. <rect class="device-rect" /> <!-- Background --> | ||
| 2. <rect class="device-selection" /> <!-- Selection outline --> | ||
| 3. <image /> or <text /> <!-- Content (image/label mode) --> | ||
| 4. <foreignObject class="drag-overlay"> <!-- Click/drag handling --> | ||
| </g> | ||
| ``` |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Ah, an untagged code block lurks in the documentation!
The code block showing the SVG structure lacks a language identifier. While not critical for research documentation, adding a language tag improves syntax highlighting and readability.
🔎 Suggested fix
-```
+```text
<g class="rack-device" transform="translate(...)">📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ``` | |
| <g class="rack-device" transform="translate(...)"> | |
| 1. <rect class="device-rect" /> <!-- Background --> | |
| 2. <rect class="device-selection" /> <!-- Selection outline --> | |
| 3. <image /> or <text /> <!-- Content (image/label mode) --> | |
| 4. <foreignObject class="drag-overlay"> <!-- Click/drag handling --> | |
| </g> | |
| ``` |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
29-29: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In docs/research/spike-237-network-interface-visualization.md around lines 29 to
36, the fenced code block showing the SVG structure is missing a language
identifier; update the opening fence to include a language tag (e.g., ```xml or
```text) to enable syntax highlighting and improve readability while keeping the
block content unchanged.
| ### Phase 1: Interface Indicators (2-3 days) | ||
| **Goal:** Show interface ports on device faces | ||
|
|
||
| | Task | Estimate | | ||
| |------|----------| | ||
| | Expand `InterfaceTemplate` type | 2h | | ||
| | Update Zod schema | 1h | | ||
| | Create `PortIndicators.svelte` component | 4h | | ||
| | Integrate into `RackDevice.svelte` | 2h | | ||
| | Add zoom-level awareness | 2h | | ||
| | Update export logic (export.ts) | 3h | | ||
| | Tests | 4h | | ||
| | **Total** | ~18h (2-3 days) | |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Excellent breakdown of Phase 1 tasks, though I sense potential time challenges!
The 18-hour estimate appears somewhat optimistic, particularly for the export logic (3h) and tests (4h). Consider that export logic must handle schema versioning and backwards compatibility, which often reveals edge cases. Similarly, comprehensive testing of zoom-level rendering, high-density grouping, and click handling across different devices may require additional time.
A buffer of 20–25% (bringing total to ~22 hours) would provide safer project planning.
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
294-294: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
🤖 Prompt for AI Agents
In docs/research/spike-237-network-interface-visualization.md around lines 294
to 306, the Phase 1 estimate is optimistic; update the task estimates to reflect
added complexity for export logic (accounting for schema versioning and
backwards compatibility) and expanded testing (zoom-level rendering,
high-density grouping, cross-device click handling), add a 20–25% buffer to the
total, and revise the table entries (increase export.ts from 3h to a realistic
value, tests from 4h to a realistic value) so the final total is approximately
~22h and include a short note explaining the buffer rationale.
| - [#237 - Spike: Network Interface Visualization](link) | ||
| - [#71 - Epic: Network Interface Visualization and Connectivity](link) |
There was a problem hiding this comment.
Placeholder links detected in the references, my friend!
The issue links contain placeholder (link) text instead of actual URLs. These should either be:
- Replaced with actual GitHub issue URLs (e.g.,
https://github.com/org/repo/issues/237) - Noted as TBD if issue numbers are not yet assigned
- Removed if not needed for research documentation
🤖 Prompt for AI Agents
In docs/research/spike-237-network-interface-visualization.md around lines 406
to 407, the reference links show the literal placeholder "(link)"; replace each
placeholder with the proper GitHub issue URL (e.g.,
https://github.com/<org>/<repo>/issues/237 and .../issues/71) or, if the issues
are not created, mark them as "TBD" or remove the entries. Ensure the chosen
change is consistent with the repo’s referencing style (absolute URL vs.
relative) and update the link text if necessary to match the final target.
Summary
Spike research for adding network interface port visualization to Rackula (#237).
Deliverables
Findings Document (
docs/research/spike-237-network-interface-visualization.md)SVG Prototype (
docs/research/prototype-port-indicators.svelte)NetBox Schema Research (
docs/research/netbox-interface-cable-schema.md)Key Findings
Recommendation
Proceed with Phase 1 implementation, targeting v0.8.0 milestone.
Test plan
Closes #237
🤖 Generated with Claude Code
Summary by CodeRabbit
Documentation
Chores
✏️ Tip: You can customize this high-level summary in your review settings.