Files

Rob Bond d69e72c3eb docs: add CLAUDE.md with project guidance for Claude Code

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-05-11 09:46:35 +01:00

3.3 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project

Real-time dashboard for monitoring Proxmox VE nodes, VMs, and LXC containers. Next.js 15 App Router with Tailwind CSS 4.

Commands

npm run dev       # Start dev server (usually on port 3002)
npm run build     # Production build
npm run start     # Start production server

Architecture

src/
├── app/
│   ├── api/               # Next.js API routes (server-side)
│   │   ├── proxy/[...]/route.js   # Reverse proxy to Proxmox web UI
│   │   ├── vnc/route.js             # VNC ticket fetcher
│   │   ├── power/route.js           # Power control (start/stop/restart)
│   │   ├── nodes/vms/lxc/route.js   # Query endpoints (aggregates across nodes)
│   │   └── status/route.js          # Aggregated summary stats
│   ├── layout.js          # Root layout (Inter font, metadata)
│   └── page.js            # Entry — renders <Dashboard />
├── components/
│   ├── Dashboard.js       # Main UI: tabs, summary cards, power action handler
│   ├── NodeList.js / NodeCard.js   # Node overview
│   ├── VMList.js / LXCList.js     # VM/LXC list views
│   ├── ConsolePanel.js    # Console embed panel
│   └── StatusBadge.js     # Status indicator
└── lib/
    └── proxmox.js         # Proxmox API client — getNodes, getVMs, getLXC, getSummary, powerControl

Key Patterns

Dual API endpoints: Queries use /api2/json, power operations use /api2/extjs. Power actions send empty body {}.
API routes aggregate data across all Proxmox nodes before returning to the client. They are thin wrappers around lib/proxmox.js.
Dashboard uses direct React state + manual axios.get() calls for power actions (instant UI sync), and SWR with refreshInterval for periodic polling of the same endpoints.
Power action flow: handlePowerAction in Dashboard.js fires POST /api/power, then immediately re-fetches all four caches (/api/nodes, /api/vms, /api/lxc, /api/status) and sets state directly. Use requestAnimationFrame flush before the API call so status messages paint.
Auth: PVEAPIToken header: Authorization: PVEAPIToken=${TOKEN_ID}=${TOKEN_SECRET}.
TLS: NODE_TLS_REJECT_UNAUTHORIZED=0 in .env.local for self-signed certs. Shows a console warning — acceptable for internal lab use.
Tailwind CSS 4: Uses @tailwindcss/postcss config. CSS vars in globals.css for theming.
All API routes return 502 on Proxmox failures with { error, data: null }.

Environment Variables

Variable	Required	Description
`PROXMOX_API_URL`	Yes	Base URL, e.g. `https://host:8006/api2/json`
`PROXMOX_TOKEN_ID`	Yes	API token ID
`PROXMOX_TOKEN_SECRET`	Yes	API token secret
`PROXMOX_WEB_URL`	No	Web UI URL (defaults from PROXMOX_API_URL)
`PROXMOX_CONSOLE_TOKEN`	No	Console session token (defaults from PROXMOX_TOKEN_ID)
`NEXT_PUBLIC_API_POLL_INTERVAL`	No	Poll interval ms (default 30000)
`NODE_TLS_REJECT_UNAUTHORIZED`	No	`0` for self-signed certs

Git Workflow

Repository is on Gitea. User works in feature branches, merges via PR. Use clean main as base. Gitea token may need to be embedded in remote URL for auth.

3.3 KiB Raw Blame History