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]

    Browser -->|Clicks UI| React
    React -->|REST Calls / SSE / WS| FastAPI
    FastAPI -->|Queries Context| K8sClient
    K8sClient -->|KubeConfig / Port 6443| Kind
    FastAPI -->|Structured Prompt| AI

Tier 1: React Frontend

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

• Dashboard High-level cluster stats with dynamic visual indicators
• Explorer Direct table representation of pods, deployments, and services
• Topology Dynamic SVG relationship mapping
• Arena Visual block programming canvas to model resources and generate clean YAML
• Concepts Tutor Chat-like AI companion

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

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.

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.