# bisman-singh/kubectl-timeline architecture

> Architecture diagram of the GitHub repository bisman-singh/kubectl-timeline, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bisman-singh/kubectl-timeline
- Repository: https://github.com/bisman-singh/kubectl-timeline

## Overview

kubectl-timeline is an agentless Kubernetes incident-timeline CLI. Its main workflow reads live cluster state, reconstructs and filters a chronological timeline, correlates incidents into root-cause chains, then renders detailed or namespace-summary output. Correlation includes documented pattern detection, cascade grouping, deduplication, and confidence ranking. The collector and main execution path are shown in excerpts; broader correlation features are represented from README documentation, not independently verified in source.

Main entry points: [`cmd/kubectl-timeline/main.go`](https://github.com/bisman-singh/kubectl-timeline/blob/main/cmd/kubectl-timeline/main.go) (CLI workflow), [`pkg/correlator/correlator.go`](https://github.com/bisman-singh/kubectl-timeline/blob/main/pkg/correlator/correlator.go) (Chain analysis), [`pkg/output/format.go`](https://github.com/bisman-singh/kubectl-timeline/blob/main/pkg/output/format.go) (Format renderers), [`pkg/timeline/types.go`](https://github.com/bisman-singh/kubectl-timeline/blob/main/pkg/timeline/types.go) (Timeline entries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Cluster collection"]
  node_collector["Cluster collector<br/>[collector.go]"]
  node_snapshot["Cluster snapshot<br/>[types.go]"]
  node_kubernetes["Kubernetes API"]
end

subgraph group_timeline["Timeline reconstruction"]
  node_builder["Timeline builder<br/>[build.go]"]
  node_entries["Timeline entries<br/>[types.go]"]
  node_filters["Timeline filters<br/>[types.go]"]
end

subgraph group_analysis["Incident analysis"]
  node_correlator["Chain analysis<br/>[correlator.go]"]
  node_patterns["Correlation patterns<br/>[correlator.go]"]
  node_dedup["Dedup and cascades<br/>[correlator.go]"]
  node_confidence["Confidence ranking<br/>[score.go]"]
end

subgraph group_presentation["Results and presentation"]
  node_formatter["Format renderers<br/>[format.go]"]
  node_affected["Affected resources<br/>[format.go]"]
  node_health["Namespace summary<br/>[format.go]"]
end

node_operator(("Operator"))
node_cli["CLI workflow<br/>[main.go]"]

node_operator -->|"runs command"| node_cli
node_cli -->|"collects state"| node_collector
node_collector -->|"lists resources"| node_kubernetes
node_collector -->|"builds snapshot"| node_snapshot
node_cli -->|"builds timeline"| node_builder
node_builder -->|"reads snapshot"| node_snapshot
node_builder -->|"creates entries"| node_entries
node_cli -->|"filters entries"| node_filters
node_filters -->|"updates entries"| node_entries
node_cli -->|"analyzes timeline"| node_correlator
node_correlator -->|"analyzes entries"| node_entries
node_correlator -->|"uses cluster state"| node_snapshot
node_correlator -->|"detects patterns"| node_patterns
node_correlator -->|"merges chains"| node_dedup
node_correlator -.->|"ranks confidence"| node_confidence
node_cli -->|"renders results"| node_formatter
node_formatter -->|"summarizes resources"| node_affected
node_cli -->|"renders summary"| node_health
node_formatter -->|"formats timeline"| node_entries
node_formatter -->|"formats chains"| node_correlator

click node_cli "https://github.com/bisman-singh/kubectl-timeline/blob/main/cmd/kubectl-timeline/main.go"
click node_collector "https://github.com/bisman-singh/kubectl-timeline/blob/main/pkg/collector/collector.go"
click node_snapshot "https://github.com/bisman-singh/kubectl-timeline/blob/main/pkg/collector/types.go"
click node_builder "https://github.com/bisman-singh/kubectl-timeline/blob/main/pkg/timeline/build.go"
click node_entries "https://github.com/bisman-singh/kubectl-timeline/blob/main/pkg/timeline/types.go"
click node_filters "https://github.com/bisman-singh/kubectl-timeline/blob/main/pkg/timeline/types.go"
click node_correlator "https://github.com/bisman-singh/kubectl-timeline/blob/main/pkg/correlator/correlator.go"
click node_patterns "https://github.com/bisman-singh/kubectl-timeline/blob/main/pkg/correlator/correlator.go"
click node_dedup "https://github.com/bisman-singh/kubectl-timeline/blob/main/pkg/correlator/correlator.go"
click node_confidence "https://github.com/bisman-singh/kubectl-timeline/blob/main/pkg/correlator/score.go"
click node_formatter "https://github.com/bisman-singh/kubectl-timeline/blob/main/pkg/output/format.go"
click node_affected "https://github.com/bisman-singh/kubectl-timeline/blob/main/pkg/output/format.go"
click node_health "https://github.com/bisman-singh/kubectl-timeline/blob/main/pkg/output/format.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_collector,node_snapshot,node_kubernetes toneBlue
class node_builder,node_entries,node_filters toneAmber
class node_correlator,node_patterns,node_dedup,node_confidence toneMint
class node_formatter,node_affected,node_health toneRose
class node_operator toneIndigo
class node_cli toneTeal
```

## Components

### Cluster collection

- [Cluster collector](https://github.com/bisman-singh/kubectl-timeline/blob/main/pkg/collector/collector.go): `pkg/collector/collector.go`
- [Cluster snapshot](https://github.com/bisman-singh/kubectl-timeline/blob/main/pkg/collector/types.go): `pkg/collector/types.go`
- **Kubernetes API**

### Timeline reconstruction

- [Timeline builder](https://github.com/bisman-singh/kubectl-timeline/blob/main/pkg/timeline/build.go): `pkg/timeline/build.go`
- [Timeline entries](https://github.com/bisman-singh/kubectl-timeline/blob/main/pkg/timeline/types.go): `pkg/timeline/types.go`
- [Timeline filters](https://github.com/bisman-singh/kubectl-timeline/blob/main/pkg/timeline/types.go): `pkg/timeline/types.go`

### Incident analysis

- [Chain analysis](https://github.com/bisman-singh/kubectl-timeline/blob/main/pkg/correlator/correlator.go): `pkg/correlator/correlator.go`
- [Correlation patterns](https://github.com/bisman-singh/kubectl-timeline/blob/main/pkg/correlator/correlator.go): `pkg/correlator/correlator.go`
- [Dedup and cascades](https://github.com/bisman-singh/kubectl-timeline/blob/main/pkg/correlator/correlator.go): `pkg/correlator/correlator.go`
- [Confidence ranking](https://github.com/bisman-singh/kubectl-timeline/blob/main/pkg/correlator/score.go): `pkg/correlator/score.go`

### Results and presentation

- [Format renderers](https://github.com/bisman-singh/kubectl-timeline/blob/main/pkg/output/format.go): `pkg/output/format.go`
- [Affected resources](https://github.com/bisman-singh/kubectl-timeline/blob/main/pkg/output/format.go): `pkg/output/format.go`
- [Namespace summary](https://github.com/bisman-singh/kubectl-timeline/blob/main/pkg/output/format.go): `pkg/output/format.go`

### Other components

- **Operator**
- [CLI workflow](https://github.com/bisman-singh/kubectl-timeline/blob/main/cmd/kubectl-timeline/main.go): `cmd/kubectl-timeline/main.go`

## Connections

- Operator → CLI workflow: runs command (evidence: `cmd/kubectl-timeline/main.go`)
- CLI workflow → Cluster collector: collects state (evidence: `cmd/kubectl-timeline/main.go`)
- Cluster collector → Kubernetes API: lists resources (evidence: `pkg/collector/collector.go`)
- Cluster collector → Cluster snapshot: builds snapshot (evidence: `pkg/collector/collector.go`)
- CLI workflow → Timeline builder: builds timeline (evidence: `cmd/kubectl-timeline/main.go`)
- Timeline builder → Cluster snapshot: reads snapshot (evidence: `pkg/timeline/build.go`)
- Timeline builder → Timeline entries: creates entries (evidence: `pkg/timeline/build.go`)
- CLI workflow → Timeline filters: filters entries (evidence: `cmd/kubectl-timeline/main.go`)
- Timeline filters → Timeline entries: updates entries (evidence: `pkg/timeline/types.go`)
- CLI workflow → Chain analysis: analyzes timeline (evidence: `cmd/kubectl-timeline/main.go`)
- Chain analysis → Timeline entries: analyzes entries (evidence: `pkg/correlator/correlator.go`)
- Chain analysis → Cluster snapshot: uses cluster state (evidence: `pkg/correlator/correlator.go`)
- Chain analysis → Correlation patterns: detects patterns (evidence: `README.md`)
- Chain analysis → Dedup and cascades: merges chains (evidence: `pkg/correlator/correlator.go`)
- Chain analysis → Confidence ranking: ranks confidence
- CLI workflow → Format renderers: renders results (evidence: `cmd/kubectl-timeline/main.go`)
- Format renderers → Affected resources: summarizes resources (evidence: `pkg/output/format.go`)
- CLI workflow → Namespace summary: renders summary (evidence: `cmd/kubectl-timeline/main.go`)
- Format renderers → Timeline entries: formats timeline (evidence: `pkg/output/format.go`)
- Format renderers → Chain analysis: formats chains (evidence: `pkg/output/format.go`)
