Architecture¶

Kubus is a small, two-tier app: a React single-page app in your browser, talking to a local Node.js server that holds the connections to your clusters. The server is the only thing that touches Kubernetes. The browser never connects to an API server directly.

graph TD
  subgraph Browser["Browser: React 19 + MUI 7 SPA"]
    UI["TanStack Query · Monaco · xterm.js"]
  end
  subgraph Server["Node.js: Fastify 5 (binds 127.0.0.1)"]
    K["@kubernetes/client-node"]
    W["watch multiplexing · log fan-in"]
    E["exec bridge · port-forward manager"]
    H["helm secret decoding · metrics"]
  end
  subgraph Clusters["Your clusters"]
    A["API server A"]
    B["API server B"]
  end
  UI -- "REST + WebSocket<br/>(token-authed, same-origin)" --> Server
  Server -- "Kubernetes API<br/>(your kubeconfig creds)" --> A
  Server --> B

The browser¶

A React 19 single-page app built with MUI 7. Notable pieces:

• TanStack Query for data fetching and caching,
• Monaco for the YAML editor and diff views,
• xterm.js for the terminals.

It talks to the server over REST and WebSocket on the same origin, carrying the access token on every request.

The server¶

A Fastify 5 server using the official @kubernetes/client-node. It does the heavy lifting that a browser can't:

• Watch multiplexing: keeps one set of informer-style watches per cluster and fans them out to every list that needs them, with automatic 410 Gone reconnect/resync.
• Log fan-in: aggregates logs from many pods into a single stream.
• Exec bridge: proxies the Kubernetes exec API to xterm.js over WebSocket, for container shells and the node shell.
• Port-forward manager: owns long-lived forwards and reports their state.
• Helm: decodes release secrets (base64 → gzip → JSON) so there's no helm binary dependency.
• Metrics: polls metrics-server and keeps a rolling history buffer for the charts.

The desktop shell¶

The desktop app is an Electron wrapper. It runs the very same server in-process on a random localhost port, opens it in a native window, and persists window state between launches. There's no separate codebase for the desktop UI; it's the same SPA.

Data flow in one sentence¶

Your browser asks the local server; the local server asks your clusters with your kubeconfig credentials; nothing leaves your machine.

See also¶