Architecture
Go backend with in-memory caches and BoltDB for auth. React frontend with live WebSocket updates.
System Diagram
SOURCE Kubernetes Cluster(s)
API Server
Kubernetes core API
Metrics Server
metrics.k8s.io/v1beta1
ENGINE KubeBolt Backend
(Go) Cluster Manager
multi-cluster lifecycle, async connection
Shared Informers
typed resources via client-go
Dynamic Client
Gateway API CRDs (unstructured)
Permission Probe
22 SSAR calls, semaphore of 10
Metrics Collector
30s poll, in-memory cache
Insights Engine
12-rule evaluation engine
Auth Service
JWT sessions, BoltDB user store
REST API (Chi v5)
lists, details, YAML, logs
WebSocket Hub
real-time broadcasts
Copilot Proxy
LLM tool-calling bridge
SURFACE KubeBolt Frontend
(React 18 · TS · Vite 5 · Tailwind) 23 Resource Views
TanStack Table + Query
Cluster Map
React Flow 11
AI Copilot
multi-provider, 16 tools
Theme System
dark/light via CSS variables
Go Workspace
Monorepo with go.work containing three modules:
apps/api— Main backend server (entry:cmd/server/main.go)packages/agent— Phase 2 lightweight node agent (stub)packages/shared— Shared Go utilities
Key Backend Packages
| Package | Purpose |
|---|---|
cluster/manager.go | Multi-cluster lifecycle, context switching, async initial connection |
cluster/connector.go | Shared informers + dynamic client, 20s cache sync timeout, 15s rest timeout |
cluster/permissions.go | RBAC probing via SSAR, cluster-wide then namespace fallback, semaphore of 10 |
cluster/nslister.go | Multi-namespace lister wrappers for namespace-scoped ServiceAccounts |
cluster/graph.go | In-memory topology graph with debounced rebuild (2s) |
cluster/relationships.go | Edge detection: ownerRefs, selectors, Gateway parentRefs, volumes |
metrics/collector.go | Metrics Server polling, per-namespace fallback, graceful degradation |
insights/engine.go | 12-rule evaluation engine |
auth/service.go | User management, JWT issue/verify, role enforcement, BoltDB persistence |
auth/middleware.go | Auth middleware with httpOnly cookie extraction and role-based route guards |
websocket/hub.go | Broadcast hub, 4096 buffer, silent drops when no clients |
api/router.go | Chi router with requireConnector middleware |
api/handlers.go | REST handlers with metrics injection, YAML, logs, deployment history |
Data Flow
- Manager reads kubeconfig contexts → async connection (HTTP server binds immediately, returns 503 until connected)
- Permission probe: 22 SSAR calls, cluster-wide then namespace fallback, ~2-5s
- Informers start only for permitted resources
- Namespace-scoped SAs → per-namespace informer factories with multi-lister aggregation
- Dynamic client discovers Gateway API CRDs (5s timeout, gracefully skipped)
- Metrics Collector polls every 30s → in-memory cache (per-namespace when cluster-wide denied)
- REST API serves enriched resources with metrics injection, paginated (50/page). 403 for restricted.
- WebSocket broadcasts resource changes with debounced topology rebuilds