Architecture¶

Overview¶

Headlamp has three runtime layers: the Go backend (headlamp-server), the React SPA (frontend), and an optional Electron shell for the desktop app. They compose differently in each deployment mode but the request lifecycle is the same.

┌─────────────────────────────────────────────────────────────────┐
│  Browser (React SPA + loaded plugins)                           │
└───────────────────────────────┬─────────────────────────────────┘
                                │ HTTP / WebSocket
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│  headlamp-server (Go)                                           │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │ Cluster      │  │ Plugin       │  │ Helm API +           │  │
│  │ proxy        │  │ serving      │  │ /serviceproxy        │  │
│  └──────┬───────┘  └──────────────┘  └──────────┬───────────┘  │
└─────────┼───────────────────────────────────────┼──────────────┘
          │ kube-apiserver API                     │ in-cluster svc
          ▼                                        ▼
   Kubernetes API                           Service (Helm repo,
   (REST + Watch)                           catalog, etc.)

Request lifecycle¶

Every user action in the UI travels the same path:

1. Browser initiates an HTTP or WebSocket request to headlamp-server (never directly to the cluster)
2. headlamp-server authenticates the request using the current token or OIDC session
3. The request is forwarded to the appropriate cluster proxy, which holds the actual cluster credentials
4. The Kubernetes API responds; the proxy returns the result to the browser

For service proxy requests (in-cluster services):

Browser → headlamp-server /serviceproxy/{ns}/{svc}/{path} → ClusterIP service

For plugin assets:

Browser → headlamp-server /plugins/{name}/main.js → static file from plugins dir

WebSocket multiplexing¶

Browsers cap concurrent WebSocket connections at approximately 6. Headlamp solves this with a multiplexer:

• One WebSocket from the browser to headlamp-server
• headlamp-server fans out to many Watch connections against the Kubernetes API servers

This enables real-time updates across dozens of resource types simultaneously. The multiplexer logic lives in backend/pkg/ and the frontend connects through a single shared channel rather than opening per-resource WebSockets.

Plugin loading¶

headlamp-server startup
  └── scan plugins dir (~/.config/Headlamp/plugins/ by default)
        └── for each subdir with main.js:
              serve at /plugins/{name}/main.js

Browser startup
  └── fetch plugin list from /plugins/
        └── for each plugin:
              fetch /plugins/{name}/main.js
              execute in global JS context
              plugin calls registerXxx() functions
              registry takes effect immediately

Deployment modes¶

Security model¶

• The browser never receives cluster credentials directly
• All cluster API calls are proxied through headlamp-server, which holds the token or mounts the service account
• RBAC is enforced cluster-side — Headlamp adapts the UI based on what the current token can do (e.g. no Edit button if the user lacks update permission on that resource)
• The service proxy requires an authenticated session; requests without a valid token are rejected before forwarding

Domain Architecture (Code Intelligence Analysis)¶

Call-graph analysis of the codebase (12,547 symbols, 25,929 relationships) reveals internal structure that the official documentation obscures. The manual architecture describes 6 domains; static analysis finds 59 distinct clusters.

Backend: Clean Boundaries¶

The Go backend aligns well with its package structure. Each cluster maps to a distinct concern:

Hidden coupling: The service proxy (backend/pkg/serviceproxy/) has its own Go package boundary, but the graph absorbs it into the Cmd cluster because createHeadlampHandler() tightly couples route registration with handler creation. The package boundary is cosmetic — the real dependency flows through the 540-line handler constructor.

Frontend: 9+ Clusters, Not "One Thing"¶

The official architecture describes "the frontend" as one layer. The graph tells a different story:

The Resource cluster (388 symbols) is the largest and least cohesive — it's the "everything else" of the frontend. The V1→V2 migration is visible in the data: V1 has notably low cohesion (53%), suggesting it's a transitional layer being replaced by V2 (71% cohesion).

Electron: Three Concerns, Not One¶

MCP is architecturally separate from Electron core. It has its own client, protocol handling, and IPC bridge. This matters because MCP is currently desktop-only — bringing it to in-cluster mode means extracting the Mcp cluster from its Electron dependency.

Critical Hotspots¶

These symbols have the widest blast radius in the codebase. Changes here require the most careful review:

Boundary Violations¶

Serviceproxy → Cmd absorption: The service proxy package has its own Go package, but RequestHandler is registered as a route handler inside createHeadlampHandler(), making it structurally part of the server. Changes to service proxy behavior require understanding the Cmd cluster context.

Plugin SDK → Frontend coupling: The plugin SDK (plugins/headlamp-plugin/) copies files from frontend/src/ into lib/. Every internal frontend refactor is a potential breaking change for the SDK. There is no versioned API boundary.