Skip to content

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

5.2 KB
Raw Blame
/**
 * A document either lives in the Library tree (`page`, `folder`) or describes
 * exactly one thing elsewhere in the app (`device`, `node`, `design`).
 *
 * Kept in sync with DOCUMENT_KINDS in `backend/app/services/doc_tree.py`.
 */
export type DocKind = 'device' | 'node' | 'design' | 'page' | 'folder'

/** Kinds the user files by hand. Everything else is placed by its link. */
export const TREE_KINDS: readonly DocKind[] = ['page', 'folder']

export interface DocumentSummary {
  id: string
  kind: DocKind
  title: string
  slug: string
  icon?: string | null
  parent_id?: string | null
  sort_order: number
  device_id?: string | null
  node_id?: string | null
  design_id?: string | null
  tags: string[]
  /** The parsed frontmatter, so the tree can badge without loading bodies. */
  frontmatter: Record<string, unknown>
  starred: boolean
  template_id?: string | null
  /**
   * The device has changed since this document's facts were snapshotted.
   * Decided by the server — the snapshot is its shape, not the inventory's.
   */
  drifted?: boolean
  reviewed_at?: string | null
  edited_at?: string | null
  facts_synced_at?: string | null
  created_at: string
  updated_at: string
}

export interface Doc extends DocumentSummary {
  body: string
  facts_snapshot?: Record<string, unknown> | null
}

export interface DocRevision {
  id: string
  document_id: string
  title: string
  reason: 'edit' | 'restore' | 'import' | 'migrate' | 'scaffold' | 'regenerate' | 'mcp' | 'sync'
  saved_at: string
  size: number
}

/**
 * How update-from-device disposed of one fact or section. Mirrors
 * `doc_reconcile.py`; the server is the single source of truth for the words.
 */
export type ChangeStatus = 'same' | 'auto' | 'conflict'

/** How a conflict is settled. `custom` carries the user's own text. */
export type ResolutionChoice = 'keep' | 'device' | 'custom'

/** One fact or section the update preview surfaced, and its disposition. */
export interface ReconcileChange {
  id: string
  name: string
  kind: 'field' | 'section'
  status: ChangeStatus
  documented: string
  device: string
  previous: string
  resolution?: ResolutionChoice | null
  custom?: string | null
}

/** What the user wants for one conflict; echoed to the server. */
export interface ResolutionItem {
  id: string
  choice: ResolutionChoice
  custom?: string | null
}

/** The read-only result of an update-from-device merge. */
export interface UpdatePreview {
  preview_id: string
  changes: ReconcileChange[]
  proposed_body: string
  summary: string[]
  /** Conflict ids still waiting on a decision — the apply refuses while any remain. */
  unresolved: string[]
}

/** A document pointing at the open one. Inverted server-side — see the route. */
export interface DocBacklink {
  doc_id: string
  title: string
  kind: DocKind
  device_id?: string | null
  /** The link as it was written, which may differ from the target's title. */
  label: string
  context: string
  count: number
}

export interface DocSearchHit {
  doc_id: string
  title: string
  kind: DocKind
  snippet: string
  device_id?: string | null
}

export interface DocSearchResult {
  /** "like" means no FTS5 — the UI drops snippet highlighting. */
  engine: 'fts5' | 'like'
  hits: DocSearchHit[]
}

export interface DocCoverage {
  devices: number
  documented: number
  header_only: number
  missing: number
  drifted: number
  overdue: number
  notes_unmigrated: number
  library_pages: number
}

/** Templates the "New document" menu offers. Mirrors `doc_template.py`. */
export const DOC_TEMPLATES = [
  { id: 'blank', label: 'Blank page', hint: 'A title and nothing else' },
  { id: 'runbook', label: 'Runbook', hint: 'Trigger, steps, rollback' },
  { id: 'service', label: 'Service', hint: 'A service spanning hosts' },
  { id: 'network', label: 'Network overview', hint: 'Topology, subnets, routing' },
  { id: 'incident', label: 'Incident', hint: 'Timeline, cause, fix' },
  { id: 'procedure', label: 'Procedure', hint: 'Goal, prerequisites, steps' },
  { id: 'decision', label: 'Decision (ADR)', hint: 'Context, decision, consequences' },
  { id: 'zone', label: 'Zone / group', hint: 'Purpose, members, addressing' },
] as const

export type DocTemplateId = (typeof DOC_TEMPLATES)[number]['id']

/** How the Devices root is pivoted. The Library tree never changes shape. */
export type GroupBy =
  | 'zone'
  | 'group'
  | 'type'
  | 'physicality'
  | 'subnet'
  | 'canvas'
  | 'rack'
  | 'vendor'
  | 'source'
  | 'status'
  | 'tag'
  | 'flat'

export const GROUP_BY_LABELS: Record<GroupBy, string> = {
  zone: 'Zone',
  group: 'Group',
  type: 'Type',
  physicality: 'Physical / virtual',
  subnet: 'Subnet',
  canvas: 'Canvas',
  rack: 'Rack',
  vendor: 'Vendor',
  source: 'Discovery source',
  status: 'Status',
  tag: 'Tag',
  flat: 'A–Z',
}

/** What the tree badge says about a device at a glance. */
export type DocState = 'none' | 'header-only' | 'written' | 'drifted' | 'overdue'

export interface TreeLeaf {
  id: string
  label: string
  docId?: string
  deviceId?: string
  nodeId?: string
  kind: DocKind | 'device-without-doc'
  state: DocState
  icon?: string | null
  children?: TreeLeaf[]
}

export interface TreeGroup {
  key: string
  label: string
  items: TreeLeaf[]
}