Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring
TypeScript diagramhomelabhomelab-infrastructure-observabilitynetworkproxmox-veself-hostedzigbeezwavezwave-js
export * from './rack'
// The rack's `Port` describes a socket on a faceplate; an inventory row carries
// the plate's ports, so the type is needed here as well as re-exported.
import type { Port } from './rack'
/**
* `network` and `electrical` render the same React Flow canvas and differ only
* by palette and node set. `rack` is a different renderer entirely (racks,
* mounted gear, port-to-port patching), so `App` branches on this.
*
* Kept in sync with DESIGN_TYPES in backend/app/schemas/designs.py.
*/
export type DesignType = 'network' | 'electrical' | 'rack'
export interface Design {
id: string
name: string
design_type: DesignType
/** Lucide icon key (see utils/designIcons). User-chosen; may be null on legacy rows. */
icon?: string | null
created_at: string
updated_at: string
/** Populated by the design list endpoint for the "copy from existing" picker. */
node_count?: number | null
group_count?: number | null
text_count?: number | null
}
export type NodeType =
| 'isp'
| 'router'
| 'firewall'
| 'switch'
| 'server'
| 'proxmox'
| 'vm'
| 'lxc'
| 'nas'
| 'kvm'
| 'iot'
| 'ap'
| 'camera'
| 'printer'
| 'computer'
| 'laptop'
| 'mobile'
| 'cpl'
| 'docker_host'
| 'docker_container'
| 'generic'
| 'groupRect'
| 'group'
| 'text'
| 'zigbee_coordinator'
| 'zigbee_router'
| 'zigbee_enddevice'
| 'zwave_coordinator'
| 'zwave_router'
| 'zwave_enddevice'
| 'grid'
| 'ups'
| 'battery'
| 'generator'
| 'solar_panel'
| 'inverter'
| 'circuit_breaker'
| 'contactor'
| 'electrical_switch'
| 'socket'
| 'light'
| 'meter'
| 'transformer'
| 'load'
export type TextPosition =
| 'top-left'
| 'top-center'
| 'top-right'
| 'middle-left'
| 'center'
| 'middle-right'
| 'bottom-left'
| 'bottom-center'
| 'bottom-right'
export type EdgeType = 'ethernet' | 'wifi' | 'iot' | 'zigbee_mesh' | 'vlan' | 'virtual' | 'cluster' | 'fibre' | 'electrical'
export type NodeStatus = 'online' | 'offline' | 'pending' | 'unknown'
export type CheckMethod = 'ping' | 'http' | 'https' | 'tcp' | 'ssh' | 'prometheus' | 'health' | 'none'
export interface ServiceInfo {
port?: number
protocol: 'tcp' | 'udp'
service_name: string
path?: string
icon?: string
category?: string
/** Overrides the node host when building the service URL — one node can serve
* several domains. Same accepted shapes as a node `ip`/`hostname`
* (`host`, `host:port`, `https://host/…`). An override suppresses `port`:
* it usually names a reverse proxy, where the scanned port breaks the URL,
* so only a port written here is used. */
host?: string
/** Whether the node drawing this device shows the service. Per node, not per
* device — the same device on another canvas keeps its own answer. Absent
* means shown: the flag only appears once the service has been hidden. */
visible?: boolean
}
export type ServiceStatus = 'online' | 'offline' | 'unknown'
export interface NodeProperty {
key: string
value: string
icon: string | null
visible: boolean
}
/**
* A Device Inventory row, as `/scan/pending` returns it.
*
* The inventory row — not the canvas node — owns what a device *is*: its
* addresses, services, properties, notes and hardware. A node describes how
* that device is drawn on one canvas. Re-exported from
* `components/modals/InventoryDeviceModal` for the call sites that predate this
* home.
*/
export interface InventoryEntry {
id: string
ip: string | null
mac: string | null
hostname: string | null
os: string | null
services: ServiceInfo[]
suggested_type: string | null
/** Inventory lifecycle: pending / approved / hidden. Not reachability. */
status: string
discovery_source?: string | null
/**
* All sources that have observed this device (e.g. ["arp", "proxmox"]). A
* merged device shows under every matching filter. Falls back to
* [discovery_source] when absent (older rows).
*/
discovery_sources?: string[]
ieee_address?: string | null
friendly_name?: string | null
device_subtype?: string | null
model?: string | null
vendor?: string | null
lqi?: number | null
properties?: NodeProperty[]
discovered_at: string
/** Curated facts, editable from the device detail modal. */
label?: string | null
type?: string | null
notes?: string | null
cpu_count?: number | null
cpu_model?: string | null
ram_gb?: number | null
disk_gb?: number | null
show_hardware?: boolean
check_method?: CheckMethod | null
check_target?: string | null
/** Live reachability from the status checker — distinct from `status`. */
status_live?: string
last_seen?: string | null
last_scan?: string | null
response_time_ms?: number | null
updated_at?: string | null
/** How many canvases (designs) this device already appears on. Server-computed. */
canvas_count?: number
/**
* Timestamps from the linked canvas node(s), correlated by ip/ieee_address.
* Null/absent when the device is not on any canvas yet.
*/
node_created_at?: string | null
node_last_scan?: string | null
node_last_modified?: string | null
node_last_seen?: string | null
/**
* Rack modelisation — the front panel this device wears in every rack it is
* mounted in. The inventory row owns it; a mount only places it. Null/absent
* until the device has been racked or modelled once.
*/
rack_faceplate_id?: string | null
rack_u_height?: number | null
rack_col_span?: number | null
rack_color?: string | null
rack_ports?: Port[]
}
export interface NodeData extends Record<string, unknown> {
label: string
type: NodeType
/**
* The Device Inventory row this node draws. The row owns the device facts
* below (ip, services, properties, notes…) — they arrive hydrated from it and
* a save routes them back to it. Null/absent for canvas furniture
* (group / groupRect / text), which describes nothing physical.
*/
device_id?: string | null
hostname?: string
ip?: string
mac?: string
os?: string
status: NodeStatus
check_method?: CheckMethod
check_target?: string
services: ServiceInfo[]
last_seen?: string
last_scan?: string
created_at?: string
updated_at?: string
response_time_ms?: number
notes?: string
/**
* Canvas furniture only (`group` / `groupRect` / `text`): what the zone or
* group is for, in the user's words. Furniture draws no device, so it has
* no inventory row to keep a `notes` field on — this is that text's only
* home, and it saves with the canvas. Always null on a node that does draw
* a device; its notes belong to the inventory row.
*/
description?: string | null
cpu_count?: number
cpu_model?: string
ram_gb?: number
disk_gb?: number
show_hardware?: boolean
properties?: NodeProperty[]
parent_id?: string
container_mode?: boolean
custom_colors?: {
border?: string
background?: string
icon?: string
show_services?: boolean
// Group rectangle extras (type === 'groupRect')
text_color?: string
text_position?: TextPosition
font?: string
border_style?: 'solid' | 'dashed' | 'dotted' | 'double' | 'none'
border_width?: number
label_position?: 'inside' | 'outside'
text_size?: number
z_order?: number
show_border?: boolean
width?: number
height?: number
}
/**
* Collapsible zone state (type === 'groupRect'). When true, the zone hides
* its descendants on the canvas. Persisted via `custom_colors.collapsed`
* round-trip for back-compat with older saves.
*/
collapsed?: boolean
custom_icon?: string
/** Number of top connection points, 0..64. Default 1. */
top_handles?: number
/** Number of bottom connection points, 0..64. Default 1 (centered). */
bottom_handles?: number
/** Number of left connection points, 0..64. Default 0 (opt-in). */
left_handles?: number
/** Number of right connection points, 0..64. Default 0 (opt-in). */
right_handles?: number
/** Show a port number (1..N) next to each connection point. */
show_port_numbers?: boolean
/**
* Text shown in place of a connection point's number, keyed by source handle
* ID ('top', 'bottom-3'…). A point without one keeps its 1..N number (#495).
*/
port_labels?: Record<string, string>
/** Text node content (type === 'text') */
text_content?: string
}
export type EdgePathStyle = 'bezier' | 'smooth'
/** How the edge line itself is drawn (independent of color/width). */
export type EdgeLineStyle = 'solid' | 'dashed' | 'dotted'
/**
* Endpoint marker shape for an edge end. `none` = no marker.
* Legacy saves stored a boolean (`true` = filled arrow) — coerced via
* `normalizeMarker` in utils/edgeMarkers.
*/
export type MarkerShape = 'none' | 'arrow' | 'arrow-open' | 'circle' | 'diamond' | 'square'
export interface Waypoint {
x: number
y: number
}
export interface EdgeData extends Record<string, unknown> {
type: EdgeType
label?: string
vlan_id?: number
speed?: string
/** Measured Zigbee link quality. Written by the import, never edited by hand. */
lqi?: number
custom_color?: string
path_style?: EdgePathStyle
/** Line render style override. Unset = use the edge type's default preset. */
line_style?: EdgeLineStyle
/** Stroke-width multiplier (1×–4×) applied to the edge type's base width. */
width_mult?: number
animated?: boolean | 'snake' | 'flow' | 'basic' | 'none'
/** Marker shape at the source end. Legacy boolean (`true`=arrow) coerced on read. */
marker_start?: MarkerShape | boolean
/** Marker shape at the target end. Legacy boolean (`true`=arrow) coerced on read. */
marker_end?: MarkerShape | boolean
waypoints?: Waypoint[]
}
export const NODE_TYPE_LABELS: Record<NodeType, string> = {
isp: 'ISP / Modem',
router: 'Router',
firewall: 'Firewall',
switch: 'Switch',
server: 'Server',
proxmox: 'Proxmox VE',
vm: 'Virtual Machine',
lxc: 'LXC Container',
nas: 'NAS',
kvm: 'KVM Switch',
iot: 'IoT Device',
ap: 'Access Point',
camera: 'Camera',
printer: 'Printer',
computer: 'Computer',
laptop: 'Laptop',
mobile: 'Phone / Mobile',
cpl: 'CPL / Powerline',
docker_host: 'Docker Host',
docker_container: 'Docker Container',
generic: 'Generic Device',
groupRect: 'Group Rectangle',
group: 'Node Group',
text: 'Text',
zigbee_coordinator: 'Zigbee Coordinator',
zigbee_router: 'Zigbee Router',
zigbee_enddevice: 'Zigbee End Device',
zwave_coordinator: 'Z-Wave Controller',
zwave_router: 'Z-Wave Router',
zwave_enddevice: 'Z-Wave End Device',
grid: 'Grid Connection',
ups: 'UPS',
battery: 'Battery',
generator: 'Generator',
solar_panel: 'Solar Panel',
inverter: 'Inverter',
circuit_breaker: 'Circuit Breaker',
contactor: 'Contactor',
electrical_switch: 'Switch',
socket: 'Socket / Outlet',
light: 'Light Fixture',
meter: 'Energy Meter',
transformer: 'Transformer',
load: 'Electrical Load',
}
export const STATUS_COLORS: Record<NodeStatus, string> = {
online: '#39d353',
offline: '#f85149',
pending: '#e3b341',
unknown: '#8b949e',
}
export const EDGE_TYPE_LABELS: Record<EdgeType, string> = {
ethernet: 'Ethernet',
wifi: 'Wi-Fi',
iot: 'IoT / Zigbee',
zigbee_mesh: 'Zigbee Mesh',
vlan: 'VLAN',
virtual: 'Virtual',
cluster: 'Cluster',
fibre: 'Fibre',
electrical: 'Electrical Wire',
}
export interface NodeTypeStyle {
borderColor: string
borderOpacity: number
bgColor: string
bgOpacity: number
iconColor: string
iconOpacity: number
width: number
height: number
/** Default connection-point counts per side for new nodes of this type. */
topHandles?: number
bottomHandles?: number
leftHandles?: number
rightHandles?: number
}
export interface EdgeTypeStyle {
color: string
opacity: number
pathStyle: EdgePathStyle
/** Line render style (solid/dashed/dotted). */
lineStyle: EdgeLineStyle
/** Stroke-width multiplier (1×–4×). */
widthMult: number
animated: 'none' | 'snake' | 'flow' | 'basic'
/** Default marker shape at the source end for new edges of this type. */
arrowStart: MarkerShape
/** Default marker shape at the target end for new edges of this type. */
arrowEnd: MarkerShape
/**
* Print the measured LQI on the link, like the label. A view preference, so
* it is read live from the custom style rather than copied onto each edge —
* no "Apply to existing" needed. Only edges that carry an `lqi` show it, so
* it is offered for the types the Zigbee import writes (`iot`, `zigbee_mesh`).
*/
showLqi?: boolean
/**
* Animation speed multiplier (0.25×–4×) for every edge of this type. Read
* live like `showLqi`, never copied onto edges. Unset = 1×.
*/
animSpeed?: number
/**
* Colour of the snake / flow highlight (`#rrggbb`), independent from the
* line colour. Read live. Unset = follow the line colour. Basic mode
* replaces the line itself, so it keeps the line colour.
*/
animColor?: string
}
export interface CustomStyleDef {
nodes: Partial<Record<NodeType, NodeTypeStyle>>
edges: Partial<Record<EdgeType, EdgeTypeStyle>>
}
export interface FloorMapConfig {
/**
* Server URL of the uploaded image (e.g. /api/v1/media/<uuid>.png).
* Legacy canvases may still hold a base64 `data:` URL — both render in <img>.
* Floor plans require a backend; they are disabled in standalone mode.
*/
imageData: string
posX: number
posY: number
width: number
height: number
opacity: number
locked: boolean
enabled: boolean
}