Skip to content

Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring

13.3 KB
Raw Blame
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
}