Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring
TypeScript diagramhomelabhomelab-infrastructure-observabilitynetworkproxmox-veself-hostedzigbeezwavezwave-js
/**
* Standalone-mode persistence (VITE_STANDALONE=true).
*
* No backend is available, so designs (multi-canvas) and their canvas data are
* persisted directly to localStorage:
* - `homelable_designs` → Design[] (the canvas list)
* - `homelable_canvas:<id>` → { nodes, edges, theme_id, custom_style } per design
* - `homelable_rack:<id>` → { racks, devices, cables, viewport } per rack design
*
* Legacy single-canvas installs stored everything under `homelable_canvas`
* (no per-design key, no design list). `ensureSeed()` migrates that data into a
* default design on first run so existing users keep their canvas.
*/
import type { Node, Edge } from '@xyflow/react'
import type {
Cable,
CustomStyleDef,
Design,
DesignType,
EdgeData,
InventoryDevice,
InventoryEntry,
NodeData,
Rack,
RackDevice,
} from '@/types'
import type { ThemeId } from '@/utils/themes'
import { generateUUID } from '@/utils/uuid'
import { FURNITURE_TYPES } from '@/utils/nodeTypeGroups'
const DESIGNS_KEY = 'homelable_designs'
const LEGACY_CANVAS_KEY = 'homelable_canvas'
const RACK_KEY = 'homelable_rack'
const canvasKey = (designId: string) => `${LEGACY_CANVAS_KEY}:${designId}`
const rackKey = (designId: string) => `${RACK_KEY}:${designId}`
export interface StandaloneRackCanvas {
racks: Rack[]
devices: RackDevice[]
cables: Cable[]
viewport?: { x: number; y: number; zoom: number }
/**
* Inventory entries created from the rack canvas. Standalone has no
* `pending_devices` table, so hardware documented here lives with the canvas.
*/
inventory: InventoryDevice[]
}
export interface StandaloneCanvas {
nodes: Node<NodeData>[]
edges: Edge<EdgeData>[]
theme_id?: ThemeId
custom_style?: CustomStyleDef | null
/**
* The Device Inventory for this canvas. Standalone has no backend, so the
* rows live with the canvas the way `StandaloneRackCanvas.inventory` does —
* but the split is the same one the API makes: a node points at a row through
* `device_id`, and the row owns the device facts. Absent on canvases saved
* before the split, whose nodes still carry those facts inline.
*/
devices?: InventoryEntry[]
// NOTE: no floor plan here — floor plans need a backend to upload/serve the
// image, so they are disabled in standalone mode (see homelable/CLAUDE.md ADR).
}
/**
* Device fields the inventory row owns — everything a node no longer keeps.
*
* `status` is deliberately absent. On a node it is live reachability
* (online/offline/unknown); on an inventory row it is the pending / approved /
* hidden lifecycle. The backend keeps them apart as `status` vs `status_live`
* and so does this — copying one into the other would leave a stored device
* reading `status: "online"`, which no inventory filter can make sense of.
*/
const DEVICE_FIELDS = [
'hostname', 'ip', 'mac', 'os', 'check_method', 'check_target',
'services', 'notes', 'cpu_count', 'cpu_model', 'ram_gb', 'disk_gb',
'show_hardware', 'properties', 'last_seen', 'last_scan', 'response_time_ms',
] as const
const LIFECYCLE_STATUSES = new Set(['pending', 'approved', 'hidden'])
/**
* Repair a row saved before the two statuses were told apart, where the node's
* reachability landed in the lifecycle field. Anything that is not a lifecycle
* value was reachability, so it moves to `status_live` and the row counts as
* approved — it is on a canvas, which is what approved means.
*/
function normalizeLifecycle(row: InventoryEntry): InventoryEntry {
if (LIFECYCLE_STATUSES.has(row.status)) return row
return { ...row, status: 'approved', status_live: row.status_live ?? row.status }
}
/**
* Split a canvas into nodes-plus-rows on the way to storage.
*
* Mirrors what the API does server-side, so a standalone canvas and a
* backed one carry the same shape: one row per device, the node keeping only
* the id of the row it draws.
*/
function splitDevices(data: StandaloneCanvas): StandaloneCanvas {
const devices: InventoryEntry[] = [...(data.devices ?? [])]
const byId = new Map(devices.map((d) => [d.id, d]))
const nodes = data.nodes.map((n) => {
if (FURNITURE_TYPES.has(n.data.type)) return n
const deviceId = n.data.device_id ?? generateUUID()
const previous = byId.get(deviceId)
const facts = Object.fromEntries(
DEVICE_FIELDS.filter((f) => n.data[f] !== undefined).map((f) => [f, n.data[f]]),
)
const row = {
...(previous
? normalizeLifecycle(previous)
: { id: deviceId, discovered_at: new Date().toISOString(), status: 'approved' }),
...facts,
id: deviceId,
label: n.data.label,
type: n.data.type,
// Reachability, kept where the backend keeps it — never in `status`.
status_live: (n.data.status as string | undefined) ?? previous?.status_live ?? 'unknown',
} as InventoryEntry
if (previous) devices[devices.indexOf(previous)] = row
else devices.push(row)
byId.set(deviceId, row)
return { ...n, data: { ...n.data, device_id: deviceId } }
})
return { ...data, nodes, devices }
}
/** Put the device facts back on the nodes, so the canvas renders unchanged. */
function hydrateDevices(data: StandaloneCanvas): StandaloneCanvas {
if (!data.devices?.length) return data
const byId = new Map(data.devices.map((d) => [d.id, d]))
return {
...data,
nodes: data.nodes.map((n) => {
const row = n.data.device_id ? byId.get(n.data.device_id) : undefined
if (!row) return n
const facts = Object.fromEntries(
DEVICE_FIELDS.filter((f) => row[f] != null).map((f) => [f, row[f]]),
)
const normalized = normalizeLifecycle(row)
return {
...n,
data: {
...n.data,
...facts,
label: row.label ?? n.data.label,
type: row.type ?? n.data.type,
// The node draws reachability; a row saved before the split carries it
// in `status`, which normalizeLifecycle has moved to `status_live`.
status: normalized.status_live ?? n.data.status,
},
} as Node<NodeData>
}),
}
}
/**
* Move a furniture description off the field it used to ride on.
*
* A zone's or group's description was written to `data.notes` before it had a
* column of its own. Standalone kept furniture whole, so that text is still in
* localStorage under the old name — hoist it once on load rather than lose it.
*/
function hoistFurnitureDescriptions(data: StandaloneCanvas): StandaloneCanvas {
return {
...data,
nodes: data.nodes.map((n) => {
if (!FURNITURE_TYPES.has(n.data.type)) return n
if (n.data.description != null || n.data.notes == null) return n
return { ...n, data: { ...n.data, description: n.data.notes } } as Node<NodeData>
}),
}
}
function readJSON<T>(key: string): T | null {
try {
const raw = localStorage.getItem(key)
return raw ? (JSON.parse(raw) as T) : null
} catch {
return null
}
}
function nowIso(): string {
return new Date().toISOString()
}
/** Read the design list. Returns [] when none have been created yet. */
export function listDesigns(): Design[] {
return readJSON<Design[]>(DESIGNS_KEY) ?? []
}
function writeDesigns(designs: Design[]): void {
localStorage.setItem(DESIGNS_KEY, JSON.stringify(designs))
}
/**
* Guarantee at least one design exists and return the full list.
* Migrates a legacy single-canvas install into a default design on first run.
*/
export function ensureSeed(): Design[] {
const existing = listDesigns()
if (existing.length > 0) return existing
const design: Design = {
id: generateUUID(),
name: 'My Homelab',
design_type: 'network',
icon: null,
created_at: nowIso(),
updated_at: nowIso(),
}
writeDesigns([design])
// Migrate legacy canvas data (stored under the bare key) into this design.
const legacy = readJSON<StandaloneCanvas>(LEGACY_CANVAS_KEY)
if (legacy && localStorage.getItem(canvasKey(design.id)) === null) {
localStorage.setItem(canvasKey(design.id), JSON.stringify(legacy))
localStorage.removeItem(LEGACY_CANVAS_KEY)
}
return [design]
}
export function createDesign(name: string, icon?: string | null, design_type: DesignType = 'network'): Design {
const design: Design = {
id: generateUUID(),
name,
design_type,
icon: icon ?? null,
created_at: nowIso(),
updated_at: nowIso(),
}
writeDesigns([...listDesigns(), design])
return design
}
const GROUP_TYPE = 'groupRect'
const TEXT_TYPE = 'text'
/** Node/group/text counts for a design's saved canvas (0s when never saved). */
export function designCounts(designId: string): Pick<Design, 'node_count' | 'group_count' | 'text_count'> {
const canvas = loadCanvas(designId)
const nodes = canvas?.nodes ?? []
let group = 0
let text = 0
let node = 0
for (const n of nodes) {
if (n.data?.type === GROUP_TYPE) group++
else if (n.data?.type === TEXT_TYPE) text++
else node++
}
return { node_count: node, group_count: group, text_count: text }
}
/** Return the design list with per-canvas counts filled in (for the copy picker). */
export function listDesignsWithCounts(): Design[] {
return listDesigns().map((d) => ({ ...d, ...designCounts(d.id) }))
}
/** Deep-copy a design's canvas into a new design. Returns the new design. */
export function copyDesign(sourceId: string, name: string, icon?: string | null): Design {
const sourceType = listDesigns().find((d) => d.id === sourceId)?.design_type ?? 'network'
const design = createDesign(name, icon, sourceType)
const source = loadCanvas(sourceId)
if (source) {
// localStorage canvas already stores React Flow nodes/edges by value; a fresh
// JSON round-trip is enough to detach the copy from the source.
saveCanvas(design.id, JSON.parse(JSON.stringify(source)) as StandaloneCanvas)
}
const sourceRack = loadRackCanvas(sourceId)
if (sourceRack) {
saveRackCanvas(design.id, JSON.parse(JSON.stringify(sourceRack)) as StandaloneRackCanvas)
}
return design
}
export function updateDesign(id: string, patch: Partial<Pick<Design, 'name' | 'icon'>>): Design | null {
const designs = listDesigns()
const idx = designs.findIndex((d) => d.id === id)
if (idx === -1) return null
const updated: Design = { ...designs[idx], ...patch, updated_at: nowIso() }
designs[idx] = updated
writeDesigns(designs)
return updated
}
export function deleteDesign(id: string): void {
writeDesigns(listDesigns().filter((d) => d.id !== id))
localStorage.removeItem(canvasKey(id))
localStorage.removeItem(rackKey(id))
}
/** Load a design's rack canvas. Returns null when it has never been saved. */
export function loadRackCanvas(designId: string): StandaloneRackCanvas | null {
return readJSON<StandaloneRackCanvas>(rackKey(designId))
}
export function saveRackCanvas(designId: string, data: StandaloneRackCanvas): void {
localStorage.setItem(rackKey(designId), JSON.stringify(data))
}
/** Load a design's canvas. Returns null when the design has never been saved. */
export function loadCanvas(designId: string): StandaloneCanvas | null {
const stored = readJSON<StandaloneCanvas>(canvasKey(designId))
return stored ? hoistFurnitureDescriptions(hydrateDevices(stored)) : null
}
export function saveCanvas(designId: string, data: StandaloneCanvas): void {
localStorage.setItem(canvasKey(designId), JSON.stringify(splitDevices(data)))
}