# roshie548/proxmux architecture

> Architecture diagram of the GitHub repository roshie548/proxmux, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/roshie548/proxmux
- Repository: https://github.com/roshie548/proxmux

## Overview

##### 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).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Bun Runtime
    subgraph "Bun Runtime"
        direction TB
        BN1["package.json"]:::bun
        BN2["bun.lock"]:::bun
        BN3["Start Commands\n(bun run start / bunx proxmux)"]:::bun
    end
    click BN1 "https://github.com/roshie548/proxmux/blob/main/package.json"
    click BN2 "https://github.com/roshie548/proxmux/blob/main/bun.lock"

    %% Application Entry
    subgraph "Application Core"
        direction TB
        AE["src/index.tsx"]:::app
        AA["src/app.tsx"]:::app
    end
    click AE "https://github.com/roshie548/proxmux/blob/main/src/index.tsx"
    click AA "https://github.com/roshie548/proxmux/blob/main/src/app.tsx"

    %% UI Layer
    subgraph "Ink TUI (App → Views → Components)" 
        direction TB
        UI1["Views (src/views)"]:::app
        UI2["Components (src/components)"]:::app
        UI3["Common Components\n(src/components/common)"]:::app
    end
    click UI1 "https://github.com/roshie548/proxmux/tree/main/src/views"
    click UI2 "https://github.com/roshie548/proxmux/tree/main/src/components"
    click UI3 "https://github.com/roshie548/proxmux/tree/main/src/components/common"

    %% Input, State, API, Config, Proc, Utils
    IH["useKeyboard Hook\n(src/hooks/useKeyboard.ts)"]:::app
    click IH "https://github.com/roshie548/proxmux/blob/main/src/hooks/useKeyboard.ts"

    CTX["EditModeContext\n(src/context/EditModeContext.tsx)"]:::app
    click CTX "https://github.com/roshie548/proxmux/blob/main/src/context/EditModeContext.tsx"

    APIc["API Client\n(src/api/client.ts)"]:::app
    click APIc "https://github.com/roshie548/proxmux/blob/main/src/api/client.ts"
    APIt["API Types\n(src/api/types.ts)"]:::app
    click APIt "https://github.com/roshie548/proxmux/blob/main/src/api/types.ts"

    CFG["Config Loader\n(src/config/index.ts)"]:::app
    click CFG "https://github.com/roshie548/proxmux/blob/main/src/config/index.ts"

    PRC["Process Launcher\n(src/hooks/useProxmox.ts)"]:::app
    click PRC "https://github.com/roshie548/proxmux/blob/main/src/hooks/useProxmox.ts"

    UTIL["Utilities\n(src/utils/format.ts)"]:::app
    click UTIL "https://github.com/roshie548/proxmux/blob/main/src/utils/format.ts"

    %% External Services
    subgraph "External Services"
        direction TB
        PE["Proxmox VE API"]:::external
        SH["Shell (pct console)"]:::external
    end

    %% Flow
    BN3 --> AE
    AE --> AA
    AA --> UI1
    UI1 --> UI2
    UI2 --> UI3

    UI2 -->|"keypress event"| IH
    IH -->|"dispatch action"| AA
    AA --> CFG
    CFG -->|provides credentials| APIc
    AA --> CTX
    AA --> APIc
    APIc --> APIt
    APIc -->|HTTP GET/POST| PE
    PE -->|JSON response| APIc
    APIc -->|data| AA
    AA --> PRC
    PRC -->|spawn console| SH
    SH -->|stream I/O| PRC
    PRC -->|UI stream| AA
    AA --> UTIL

    %% Legend Styles
    classDef bun fill:#e0f5e6,stroke:#3c763d,color:#3c763d;
    classDef app fill:#e6f0fa,stroke:#31708f,color:#31708f;
    classDef external fill:#fff4e5,stroke:#8a6d3b,color:#8a6d3b;
```
