# 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