Architecture

Architecture

Podex is designed as a local two-tier desktop daemon service running via Docker Compose. It binds directly to your active local Kubernetes cluster.

graph TD
    Browser[Browser / UI]
    React[React Frontend]
    FastAPI[FastAPI Backend]
    K8sClient[Official Python Kubernetes Client]
    Kind[Kind / Minikube Local Cluster]
    AI[Gemini / OpenAI API]
    PortForward[kubectl port-forward subprocess]
    WSUpdates[WebSocket Update Stream]

    Browser -->|Clicks UI| React
    React -->|REST / SSE / WS| FastAPI
    FastAPI -->|Queries Context| K8sClient
    FastAPI -->|Spawns / Kills| PortForward
    PortForward -->|Exposes| Kind
    K8sClient -->|KubeConfig / Port 6443| Kind
    FastAPI -->|Structured Prompt| AI
    FastAPI -->|Pushes via| WSUpdates
    WSUpdates -->|Real-time Data| React

Tier 1: React Frontend

Built with React 19, Vite, TypeScript, and Tailwind CSS 4. Runs in the user's browser, fetching API data from the FastAPI backend. Implements a stateful client layout with tabs:

• Dashboard Cluster health donut, pod status matrix, needs-attention panel, poddy chat
• Explorer Table views for 9 resource types with port forwarding, bulk delete, WebSocket updates
• Topology Dynamic column-based React Flow mapping with pan/zoom and drag-repositioning
• Arena Visual React Flow canvas to model resources and generate YAML, persisted via sessionStorage
• Concepts Tutor Chat-like AI companion with structured explanations, analogies, and troubleshooting

Tier 2: FastAPI Backend

Built with FastAPI and Python. Acts as a proxy between the UI client and the Kubernetes api-server. Stateless design — all state resides inside your Kubernetes cluster.

• Translates listing requests and streams logs using Server-Sent Events (SSE)
• Establishes real-time terminal shells inside containers using WebSocket connections
• Manages kubectl port-forward subprocess lifecycles with --address 0.0.0.0
• Pushes real-time resource updates via WebSocket (/api/ws/updates)

Local Cluster Connectivity

When running inside Docker, the backend loads the host's ~/.kube/config context. If the endpoint points to localhost or 127.0.0.1, it dynamically replaces it with host.docker.internal so the container can route to the host cluster daemon. SSL verification is skipped for local development certificates.

Cloud Shell

Docker Desktop-style terminal panel at the bottom of the page with drag-to-resize handle. Uses WebSocket-backed xterm.js shell with kubectl and bash commands. On Windows, uses Git Bash for Linux command support.

AI Provider Integration

Coordinates structured prompts containing actual cluster state, timeline logs, and resource descriptions. Leverages Google Gemini and OpenAI models. Includes fallback to mock sandbox providers when no API keys are present, making the app fully functional offline.