Christopher Mayor
3dc5d236a2
- 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
87 lines
3.1 KiB
Markdown
87 lines
3.1 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|