How roshie548/proxmux works
Project Type and Purpose
• This is a single‐binary Terminal UI (TUI) client for managing Proxmox VE clusters.
• Built on the Bun runtime and Ink (React-style components for CLI).
• It provides dashboards, VM/container operations, and shell access via the Proxmox REST API (and pct console).
High-Level Architectural Components
A. Bun Runtime
• Starts the application (bun run start, bunx proxmux)
• Hosts the TypeScript compiler (via bun tsc) and package manager
B. CLI TUI Application
• Entry point: index.tsx → renders <App> (src/app.tsx) into the terminal via Ink
• UI Layer: React-style components (src/components, src/views) handling layout, lists, modals, detail pages
• Input Layer: Ink event handlers + custom hooks (src/hooks/useKeyboard.ts) to map keystrokes to actions
C. State & Context
• EditModeContext (src/context) controls read/write modes
• Hooks & utilities manage asynchronous data fetch and UI state
D. API Client
• src/api/client.ts: wraps HTTP requests to Proxmox VE (GET, POST on endpoints)
• src/api/types.ts: TypeScript interfaces for Proxmox data models
E. Configuration Loader
• src/config/index.ts: reads ~/.config/proxmux/config.json or environment variables
• Provides host URL, credentials (token/user) to the API client
F. Process Launcher
• Uses Bun’s child_process or spawn to run pct console for container SSH sessions
G. Proxmox VE (External Service)
• Exposes REST API for cluster management
• Authorizes via API token or user credentials
Component Interactions & Data Flow
1. Startup
• Bun invokes index.tsx → Ink renders <App> → global context & config are initialized
2. User Input
• Keystroke captured by Ink → useKeyboard hook → dispatches navigation or action event
3. Data Fetch
• Upon navigation / refresh, API client constructs HTTP request with config credentials → Proxmox REST API
• JSON response → parsed into TS types → stored in state/context
4. Rendering
• Components (Dashboard, VMs, Containers, Storage, DetailView) re-render with latest data
• StatusBar, Sidebar reflect current view & loading/error states
5. Action Execution
• Start/Stop/Reboot → API client POST to relevant Proxmox endpoint → update UI on success/failure
• Console Access → spawn pct console subprocess → stream I/O into the Ink canvas
6. Exit
• Cleanup child process if running → Ink unmount → Bun process exits
Architectural Patterns & Design Principles
• Component-Based UI: reusable building blocks under src/components/common
• Hooks & Context: separation of concerns for keyboard, API, edit-mode state
• Layered Structure:
1. Presentation (views, components)
2. Business Logic (hooks, context)
3. Data Access (API client)
4. External Integration (Proxmox API, child process)
• Single Responsibility: each module has a clear role
• Labels: “Bun Runtime”, “Ink TUI (App → Views → Components)”, “useKeyboard + Hooks”, “API Client”, “Config Loader”, “Process Launcher”, “Proxmox VE API”, “Shell (pct console)”.
• On configuration sources (file vs. env).