# kubetail-org/kubetail architecture

> Architecture diagram of the GitHub repository kubetail-org/kubetail, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kubetail-org/kubetail
- Repository: https://github.com/kubetail-org/kubetail

## Overview

Kubetail is a Kubernetes log-tail platform: users start the dashboard or terminal workflow, select workloads and time/source filters, retrieve container logs and follow changing containers, then inspect a chronological merged stream. The dashboard UI communicates with the dashboard GraphQL endpoint; the dashboard uses Kubernetes connections for core data and can proxy advanced requests to the separately installable Cluster API and Cluster Agent. The CLI also offers direct terminal log streaming and Cluster API lifecycle commands. README documents search, metadata, and system-log capabilities beyond the sampled implementation; their precise resolver wiring is not shown here.

Main entry points: [`modules/cli/cmd`](https://github.com/kubetail-org/kubetail/tree/main/modules/cli/cmd) (Kubetail CLI), [`modules/dashboard/graph/server.go`](https://github.com/kubetail-org/kubetail/blob/main/modules/dashboard/graph/server.go) (Dashboard GraphQL), [`modules/cluster-api/graph/server.go`](https://github.com/kubetail-org/kubetail/blob/main/modules/cluster-api/graph/server.go) (Cluster API GraphQL), [`modules/shared/k8shelpers/connection-manager.go`](https://github.com/kubetail-org/kubetail/blob/main/modules/shared/k8shelpers/connection-manager.go) (Kubernetes connections)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_cli["Kubetail CLI"]
  node_cli_logs["CLI log commands<br/>[logs.go]"]
  node_cli_client["Cluster API client<br/>[client.go]"]
  node_cluster_ops["Cluster operations<br/>[cluster.go]"]
end

subgraph group_dashboard["Dashboard experience"]
  node_dashboard_app["Dashboard app<br/>[app.go]"]
  node_ui_routes["UI routes<br/>[routes.tsx]"]
  node_home["Workload home"]
  node_console["Log console"]
  node_log_viewer["Log viewer"]
  node_dashboard_gql["Dashboard GraphQL<br/>[server.go]"]
  node_dashboard_ops["Dashboard operations<br/>[ops.ts]"]
  node_proxy["Cluster API proxy<br/>[proxy.go]"]
  node_preferences[("User preferences<br/>[store.go]")]
end

subgraph group_logdata["Log retrieval"]
  node_connection_manager["Kubernetes connections"]
  node_shared_logs["Log fetching and streams"]
end

subgraph group_clusterapi["Cluster API services"]
  node_cluster_gql["Cluster API GraphQL<br/>[server.go]"]
  node_cluster_app["Cluster API app<br/>[app.go]"]
  node_agent["Cluster Agent<br/>[main.rs]"]
  node_metadata["Log metadata<br/>[log_metadata.rs]"]
  node_records["Log records<br/>[log_records.rs]"]
end

node_user(("User"))
node_kubernetes["Kubernetes API"]

node_user -->|"runs command"| node_cli
node_user -->|"opens dashboard"| node_ui_routes
node_cli -->|"starts server"| node_dashboard_app
node_ui_routes -->|"routes home"| node_home
node_ui_routes -->|"routes console"| node_console
node_home -->|"requests workload data"| node_dashboard_ops
node_console -->|"requests log data"| node_dashboard_ops
node_dashboard_ops -->|"sends GraphQL"| node_dashboard_gql
node_dashboard_app -->|"mounts endpoint"| node_dashboard_gql
node_dashboard_gql -->|"uses connections"| node_connection_manager
node_connection_manager -->|"reads cluster data"| node_kubernetes
node_console -->|"renders stream"| node_log_viewer
node_cli -->|"dispatches logs"| node_cli_logs
node_cli_logs -->|"fetches and streams"| node_shared_logs
node_shared_logs -->|"queries Kubernetes"| node_connection_manager
node_dashboard_gql -.->|"forwards advanced requests"| node_proxy
node_proxy -.->|"proxies GraphQL"| node_cluster_gql
node_cluster_app -->|"mounts endpoint"| node_cluster_gql
node_cluster_gql -->|"uses connections"| node_connection_manager
node_cluster_gql -.->|"dispatches agent requests"| node_agent
node_agent -->|"serves metadata"| node_metadata
node_agent -->|"serves records"| node_records
node_dashboard_gql -->|"persists settings"| node_preferences
node_cli -->|"calls API client"| node_cli_client
node_cli -->|"dispatches cluster commands"| node_cluster_ops
node_cluster_ops -->|"manages Cluster API"| node_cli_client

click node_cli "https://github.com/kubetail-org/kubetail/tree/main/modules/cli/cmd"
click node_dashboard_app "https://github.com/kubetail-org/kubetail/blob/main/modules/dashboard/pkg/app/app.go"
click node_ui_routes "https://github.com/kubetail-org/kubetail/blob/main/dashboard-ui/src/routes.tsx"
click node_home "https://github.com/kubetail-org/kubetail/tree/main/dashboard-ui/src/pages/home"
click node_console "https://github.com/kubetail-org/kubetail/tree/main/dashboard-ui/src/pages/console"
click node_log_viewer "https://github.com/kubetail-org/kubetail/tree/main/dashboard-ui/src/components/widgets/log-viewer"
click node_dashboard_gql "https://github.com/kubetail-org/kubetail/blob/main/modules/dashboard/graph/server.go"
click node_dashboard_ops "https://github.com/kubetail-org/kubetail/blob/main/dashboard-ui/src/lib/graphql/dashboard/ops.ts"
click node_connection_manager "https://github.com/kubetail-org/kubetail/blob/main/modules/shared/k8shelpers/connection-manager.go"
click node_shared_logs "https://github.com/kubetail-org/kubetail/tree/main/modules/shared/logs"
click node_cli_logs "https://github.com/kubetail-org/kubetail/blob/main/modules/cli/cmd/logs.go"
click node_cli_client "https://github.com/kubetail-org/kubetail/blob/main/modules/cli/internal/clusterapi/client.go"
click node_proxy "https://github.com/kubetail-org/kubetail/blob/main/modules/dashboard/internal/cluster-api/proxy.go"
click node_cluster_gql "https://github.com/kubetail-org/kubetail/blob/main/modules/cluster-api/graph/server.go"
click node_cluster_app "https://github.com/kubetail-org/kubetail/blob/main/modules/cluster-api/internal/app/app.go"
click node_agent "https://github.com/kubetail-org/kubetail/blob/main/crates/cluster_agent/src/main.rs"
click node_metadata "https://github.com/kubetail-org/kubetail/blob/main/crates/cluster_agent/src/log_metadata.rs"
click node_records "https://github.com/kubetail-org/kubetail/blob/main/crates/cluster_agent/src/log_records.rs"
click node_preferences "https://github.com/kubetail-org/kubetail/blob/main/modules/dashboard/pkg/preferences/store.go"
click node_cluster_ops "https://github.com/kubetail-org/kubetail/blob/main/modules/cli/cmd/cluster.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_cli_logs,node_cli_client,node_cluster_ops,node_user toneBlue
class node_dashboard_app,node_ui_routes,node_home,node_console,node_log_viewer,node_dashboard_gql,node_dashboard_ops,node_proxy,node_preferences toneAmber
class node_connection_manager,node_shared_logs,node_kubernetes toneMint
class node_cluster_gql,node_cluster_app,node_agent,node_metadata,node_records toneRose
```

## Components

### User entry points

- [Kubetail CLI](https://github.com/kubetail-org/kubetail/tree/main/modules/cli/cmd): `modules/cli/cmd`
- [CLI log commands](https://github.com/kubetail-org/kubetail/blob/main/modules/cli/cmd/logs.go): `modules/cli/cmd/logs.go`
- [Cluster API client](https://github.com/kubetail-org/kubetail/blob/main/modules/cli/internal/clusterapi/client.go): `modules/cli/internal/clusterapi/client.go`
- [Cluster operations](https://github.com/kubetail-org/kubetail/blob/main/modules/cli/cmd/cluster.go): `modules/cli/cmd/cluster.go`

### Dashboard experience

- [Dashboard app](https://github.com/kubetail-org/kubetail/blob/main/modules/dashboard/pkg/app/app.go): `modules/dashboard/pkg/app/app.go`
- [UI routes](https://github.com/kubetail-org/kubetail/blob/main/dashboard-ui/src/routes.tsx): `dashboard-ui/src/routes.tsx`
- [Workload home](https://github.com/kubetail-org/kubetail/tree/main/dashboard-ui/src/pages/home): `dashboard-ui/src/pages/home`
- [Log console](https://github.com/kubetail-org/kubetail/tree/main/dashboard-ui/src/pages/console): `dashboard-ui/src/pages/console`
- [Log viewer](https://github.com/kubetail-org/kubetail/tree/main/dashboard-ui/src/components/widgets/log-viewer): `dashboard-ui/src/components/widgets/log-viewer`
- [Dashboard GraphQL](https://github.com/kubetail-org/kubetail/blob/main/modules/dashboard/graph/server.go): `modules/dashboard/graph/server.go`
- [Dashboard operations](https://github.com/kubetail-org/kubetail/blob/main/dashboard-ui/src/lib/graphql/dashboard/ops.ts): `dashboard-ui/src/lib/graphql/dashboard/ops.ts`
- [Cluster API proxy](https://github.com/kubetail-org/kubetail/blob/main/modules/dashboard/internal/cluster-api/proxy.go): `modules/dashboard/internal/cluster-api/proxy.go`
- [User preferences](https://github.com/kubetail-org/kubetail/blob/main/modules/dashboard/pkg/preferences/store.go): `modules/dashboard/pkg/preferences/store.go`

### Log retrieval

- [Kubernetes connections](https://github.com/kubetail-org/kubetail/blob/main/modules/shared/k8shelpers/connection-manager.go): `modules/shared/k8shelpers/connection-manager.go`
- [Log fetching and streams](https://github.com/kubetail-org/kubetail/tree/main/modules/shared/logs): `modules/shared/logs`

### Cluster API services

- [Cluster API GraphQL](https://github.com/kubetail-org/kubetail/blob/main/modules/cluster-api/graph/server.go): `modules/cluster-api/graph/server.go`
- [Cluster API app](https://github.com/kubetail-org/kubetail/blob/main/modules/cluster-api/internal/app/app.go): `modules/cluster-api/internal/app/app.go`
- [Cluster Agent](https://github.com/kubetail-org/kubetail/blob/main/crates/cluster_agent/src/main.rs): `crates/cluster_agent/src/main.rs`
- [Log metadata](https://github.com/kubetail-org/kubetail/blob/main/crates/cluster_agent/src/log_metadata.rs): `crates/cluster_agent/src/log_metadata.rs`
- [Log records](https://github.com/kubetail-org/kubetail/blob/main/crates/cluster_agent/src/log_records.rs): `crates/cluster_agent/src/log_records.rs`

### Other components

- **User**
- **Kubernetes API**

## Connections

- User → Kubetail CLI: runs command
- User → UI routes: opens dashboard
- Kubetail CLI → Dashboard app: starts server
- UI routes → Workload home: routes home
- UI routes → Log console: routes console
- Workload home → Dashboard operations: requests workload data
- Log console → Dashboard operations: requests log data
- Dashboard operations → Dashboard GraphQL: sends GraphQL
- Dashboard app → Dashboard GraphQL: mounts endpoint
- Dashboard GraphQL → Kubernetes connections: uses connections
- Kubernetes connections → Kubernetes API: reads cluster data
- Log console → Log viewer: renders stream
- Kubetail CLI → CLI log commands: dispatches logs
- CLI log commands → Log fetching and streams: fetches and streams
- Log fetching and streams → Kubernetes connections: queries Kubernetes
- Dashboard GraphQL → Cluster API proxy: forwards advanced requests
- Cluster API proxy → Cluster API GraphQL: proxies GraphQL
- Cluster API app → Cluster API GraphQL: mounts endpoint
- Cluster API GraphQL → Kubernetes connections: uses connections
- Cluster API GraphQL → Cluster Agent: dispatches agent requests
- Cluster Agent → Log metadata: serves metadata
- Cluster Agent → Log records: serves records
- Dashboard GraphQL → User preferences: persists settings
- Kubetail CLI → Cluster API client: calls API client
- Kubetail CLI → Cluster operations: dispatches cluster commands
- Cluster operations → Cluster API client: manages Cluster API