# benc-uk/kubeview architecture

> Architecture diagram of the GitHub repository benc-uk/kubeview, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/benc-uk/kubeview
- Repository: https://github.com/benc-uk/kubeview

## Overview

##### Project type and purpose
- KubeView is a full-stack web application for visualizing Kubernetes clusters in real time.
- Backend is written in Go; frontend is a static HTML/JS app using Cytoscape.js for graph rendering, Alpine.js for interactivity, and Bulma for styling.

##### File structure
- Top-level directories:
- server/ – Go API server code (main.go, api.go, routes.go, config.go, sse.go) and services/ for Kubernetes client logic.
- public/ – static assets served to the browser: HTML fragments, CSS, JS modules (graph.js, main.js, side-panel.js, etc.), images.
- deploy/ – Dockerfile + Helm chart for Kubernetes deployment.
- .dev/ – development tool configs (linters, Prettier, Go tools).
- Config files: go.mod/go.sum, makefile, Dockerfile, Helm chart (Chart.yaml, templates), GitHub workflows.

##### README for additional insights
- REST endpoints (/api/*, /updates SSE, /health).
- Real-time updates via Server-Sent Events using a generated clientID.
- Two Kubernetes authentication modes: in-cluster (service account) or external kubeconfig.
- Helm chart includes service account, role, role binding.

a. Main components
- Web browser (client)
- Static asset server (Go server serving /public)
- API layer (Go HTTP router handling REST & SSE endpoints)
- SSE manager (per-client streams)
- Kubernetes API server (external system)
- Helm-deployed KubeView Pod + ServiceAccount (when in-cluster)
b. Relationships & interactions
- Browser loads index.html → fetches CSS/JS/HTML fragments.
- JS initializes: generates local clientID; requests /api/namespaces & /api/fetch; opens /updates SSE.
- Go API fetches data from Kubernetes API (via client-go), streams changes over SSE.
- Browser renders resource graph, listens for SSE updates to mutate the Cytoscape graph.
- User interactions trigger additional API calls (/api/logs, /api/status).
c. Architectural patterns
- Separation of concerns: static assets vs. API vs. streaming.
- Event-driven updates (SSE).
- Single binary Go server bundling frontend & API.
- Helm chart abstracts deployment concerns (RBAC, ingress, service).
d. Key technologies
- Go + client-go for backend
- HTML/CSS/ES6 JavaScript front end
- Cytoscape.js for graph visualization
- Alpine.js for UI bindings
- Bulma CSS framework
- Server-Sent Events for push notifications
- Helm & Docker for deployment

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client (Browser)"
        Browser["Web Browser Client"]:::frontend
    end

    subgraph "Server (KubeView Server)"
        Static["Static Asset Server<br/>(serves /public)"]:::backend
        REST["REST API Layer<br/>(/api/*)"]:::backend
        SSE["SSE Manager<br/>(/updates)"]:::backend
        KubeClient["Kubernetes Service Client"]:::backend
        Config["Server Configuration<br/>(in-cluster vs external kubeconfig)"]:::backend
    end

    Kubernetes["Kubernetes API Server"]:::external

    subgraph "Deployment"
        Docker["Docker Build"]:::deployment
        Helm["Helm Deployment"]:::deployment
    end

    Tooling["Development Tooling"]:::tooling
    Docs["Project Documentation and Diagrams"]:::docs

    Browser -->|"GET /index.html<br/>loads CSS/JS"| Static
    Browser -->|"HTTP GET /api/*"| REST
    Browser -->|"SSE /updates"| SSE
    REST -->|"watch/get"| KubeClient
    SSE -->|"stream events"| Browser
    KubeClient -->|"HTTPS"| Kubernetes
    Config -->|"configures"| KubeClient

    Docker -->|"builds image"| Static
    Docker -->|"includes binary & assets"| REST
    Helm -->|"deploys Pod & RBAC to cluster"| Kubernetes

    click Browser "https://github.com/benc-uk/kubeview/blob/main/public/index.html"
    click Static "https://github.com/benc-uk/kubeview/blob/main/server/main.go"
    click Static "https://github.com/benc-uk/kubeview/blob/main/server/routes.go"
    click REST "https://github.com/benc-uk/kubeview/blob/main/server/api.go"
    click REST "https://github.com/benc-uk/kubeview/blob/main/server/routes.go"
    click SSE "https://github.com/benc-uk/kubeview/blob/main/server/sse.go"
    click KubeClient "https://github.com/benc-uk/kubeview/blob/main/server/services/kubernetes.go"
    click Config "https://github.com/benc-uk/kubeview/blob/main/server/config.go"
    click Docker "https://github.com/benc-uk/kubeview/tree/main/deploy/Dockerfile"
    click Helm "https://github.com/benc-uk/kubeview/blob/main/deploy/helm/kubeview/Chart.yaml"
    click Tooling "https://github.com/benc-uk/kubeview/tree/main/.dev/"
    click Docs "https://github.com/benc-uk/kubeview/tree/main/docs/"

    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
    classDef deployment fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef tooling fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef docs fill:#F5DEB3,stroke:#333,stroke-width:1px
```
