Files

Christopher Mayor 3dc5d236a2 feat: expand discovery with systemd services, LXC/VMs, SSH terminal, and filebrowser

- Add systemd service discovery to backend
- Add Proxmox LXC/VM detection
- Add hostType field to config for better host categorization
- Fix SSH trust between hosts (ubuntu/grizzley -> truenas/proxmox)
- Add SSH terminal support via xterm.js
- Add filebrowser for browsing host filesystems
- Update frontend types and components for new node types

2026-02-20 17:18:33 -08:00

3.1 KiB

Raw Permalink Blame History

PROJECT KNOWLEDGE BASE

Generated: 2026-02-19 Commit: a4cff98 Branch: (current)

OVERVIEW

Homelab topology visualizer - React + Express full-stack app displaying infrastructure as interactive graph (network → hosts → containers → volumes).

STRUCTURE

./
├── server/           # Express API backend
│   └── routes/       # API endpoints (discover, config, stats, files)
├── src/              # React frontend
│   ├── components/   # UI components (Header, LeftPanel, RightPanel, Graph)
│   ├── services/     # Discovery logic
│   ├── store/        # Zustand state
│   ├── types/        # TypeScript definitions
│   └── utils/        # Utilities
├── docker/           # Nginx + Dockerfile
├── dist/             # Built frontend (committed - non-standard)
└── index.html        # Frontend entry

WHERE TO LOOK

Task	Location	Notes
Add API endpoint	server/routes/*.ts	Modular route files
Add UI component	src/components/*.tsx	React components
State management	src/store/topologyStore.ts	Zustand store
Discovery logic	src/services/discovery.ts	Data transformation
SSH discovery	src/services/sshDiscovery.ts	SSH connectivity

CODE MAP

Symbol	Type	Location	Role
App	component	src/App.tsx	Main orchestrator
TopologyGraph	component	src/components/Graph/TopologyGraph.tsx	Graph rendering
useTopologyStore	hook	src/store/topologyStore.ts	Global state
discoverRouter	router	server/routes/discover.ts	/api/discover

CONVENTIONS (THIS PROJECT)

TypeScript: Strict mode enabled, ESNext modules
Path alias: @/* maps to src/*
Frontend: React 18 + Vite + Tailwind CSS + Zustand
Backend: Express 5 + TypeScript (tsx runtime)
Graph: @xyflow/react (React Flow) + dagre layout
Build: tsc -b && vite build
Lint: eslint . (flat config)
Run dev: npm run dev (frontend), npm run server (backend)

ANTI-PATTERNS (THIS PROJECT)

DO NOT commit dist/: Build artifacts in dist/ are committed - should be in .gitignore
DO NOT skip tsc: Build script runs tsc -b before vite - don't remove
DO NOT use localStorage for SSH credentials: Security risk (documented in .sisyphus/plans)

UNIQUE STYLES

Dual runtime: frontend (Vite) + backend (tsx server/index.ts)
Fallback to simulated data if API unavailable
Polling-based live updates (configurable interval)
Graph auto-layout with dagre

COMMANDS

npm run dev          # Frontend dev server (localhost:3000)
npm run server       # Backend API server (localhost:3001)
npm run build        # TypeScript + Vite build
npm run lint         # ESLint check
npm run discover     # Run SSH discovery standalone

NOTES

Frontend expects API at http://localhost:3001 (configurable via VITE_API_URL)
API routes mounted under /api/*
CORS configured for http://localhost:3000 only
SSH discovery uses ssh2 library - requires network access to hosts

3.1 KiB Raw Permalink Blame History