# derailed/popeye architecture

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

- Interactive diagram: https://gitdiagram.com/derailed/popeye
- Repository: https://github.com/derailed/popeye

## Overview

Popeye is a read-only Kubernetes live-cluster linter. The main workflow is CLI invocation, configuration and cluster initialization, loading resources into an in-memory database, running resource linters, collecting findings, and emitting a scored report. The README documents resource checks, namespace and section selection, configuration, multiple report formats, and optional Prometheus metrics; the tree also shows Cilium-specific linting. Source excerpts do not expose every runtime registration or integration, so uncertain connections are omitted.

Main entry points: [`pkg/popeye.go`](https://github.com/derailed/popeye/blob/master/pkg/popeye.go) (Scan coordinator), [`internal/db/db.go`](https://github.com/derailed/popeye/blob/master/internal/db/db.go) (In-memory resource DB), [`cmd/root.go`](https://github.com/derailed/popeye/blob/master/cmd/root.go) (CLI commands), [`internal/lint/pod.go`](https://github.com/derailed/popeye/blob/master/internal/lint/pod.go) (Resource linters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and configuration"]
  node_main["Program entry<br/>[main.go]"]
  node_cli["CLI commands<br/>[root.go]"]
  node_config["Scan configuration"]
end

subgraph group_scan["Cluster scan"]
  node_popeye["Scan coordinator<br/>[popeye.go]"]
  node_client["Kubernetes client<br/>[client.go]"]
  node_factory["Resource factory<br/>[factory.go]"]
  node_loader["Resource loader<br/>[loader.go]"]
  node_database[("In-memory resource DB<br/>[db.go]")]
end

subgraph group_checks["Lint and findings"]
  node_scrub["Resource scrubbers"]
  node_linters["Resource linters<br/>[pod.go]"]
  node_cilium["Cilium policy lint<br/>[ccnp.go]"]
  node_issues["Finding collection<br/>[collector.go]"]
end

subgraph group_output["Reports and metrics"]
  node_builder["Report builder<br/>[builder.go]"]
  node_writer["Report output<br/>[writer.go]"]
  node_prometheus["Prometheus metrics<br/>[prometheus.go]"]
end

node_operator(("Operator"))
node_kube[("Kubernetes cluster")]

node_operator -->|"invokes"| node_main
node_main -->|"dispatches"| node_cli
node_cli -->|"starts scan"| node_popeye
node_cli -->|"sets flags"| node_config
node_popeye -->|"loads config"| node_config
node_popeye -->|"initializes client"| node_client
node_client -->|"queries API"| node_kube
node_popeye -->|"creates factory"| node_factory
node_factory -.->|"reads resources"| node_kube
node_popeye -->|"initializes DB"| node_database
node_loader -->|"loads resources"| node_database
node_popeye -->|"runs lint"| node_linters
node_linters -->|"reads resources"| node_database
node_linters -->|"records findings"| node_issues
node_popeye -->|"adds outcomes"| node_builder
node_builder -->|"formats report"| node_writer
node_builder -.->|"publishes metrics"| node_prometheus
node_popeye -.->|"runs lint"| node_cilium
node_scrub -.->|"uses resource DB"| node_database

click node_main "https://github.com/derailed/popeye/blob/master/main.go"
click node_cli "https://github.com/derailed/popeye/blob/master/cmd/root.go"
click node_config "https://github.com/derailed/popeye/tree/master/pkg/config"
click node_popeye "https://github.com/derailed/popeye/blob/master/pkg/popeye.go"
click node_client "https://github.com/derailed/popeye/blob/master/internal/client/client.go"
click node_factory "https://github.com/derailed/popeye/blob/master/internal/client/factory.go"
click node_loader "https://github.com/derailed/popeye/blob/master/internal/db/loader.go"
click node_database "https://github.com/derailed/popeye/blob/master/internal/db/db.go"
click node_scrub "https://github.com/derailed/popeye/tree/master/internal/scrub"
click node_linters "https://github.com/derailed/popeye/blob/master/internal/lint/pod.go"
click node_cilium "https://github.com/derailed/popeye/blob/master/internal/cilium/lint/ccnp.go"
click node_issues "https://github.com/derailed/popeye/blob/master/internal/issues/collector.go"
click node_builder "https://github.com/derailed/popeye/blob/master/internal/report/builder.go"
click node_writer "https://github.com/derailed/popeye/blob/master/internal/report/writer.go"
click node_prometheus "https://github.com/derailed/popeye/blob/master/internal/report/prometheus.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_main,node_cli,node_config toneBlue
class node_popeye,node_client,node_factory,node_loader,node_database,node_kube toneAmber
class node_scrub,node_linters,node_cilium,node_issues toneMint
class node_builder,node_writer,node_prometheus toneRose
class node_operator toneIndigo
```

## Components

### CLI and configuration

- [Program entry](https://github.com/derailed/popeye/blob/master/main.go): `main.go`
- [CLI commands](https://github.com/derailed/popeye/blob/master/cmd/root.go): `cmd/root.go`
- [Scan configuration](https://github.com/derailed/popeye/tree/master/pkg/config): `pkg/config`

### Cluster scan

- [Scan coordinator](https://github.com/derailed/popeye/blob/master/pkg/popeye.go): `pkg/popeye.go`
- [Kubernetes client](https://github.com/derailed/popeye/blob/master/internal/client/client.go): `internal/client/client.go`
- [Resource factory](https://github.com/derailed/popeye/blob/master/internal/client/factory.go): `internal/client/factory.go`
- [Resource loader](https://github.com/derailed/popeye/blob/master/internal/db/loader.go): `internal/db/loader.go`
- [In-memory resource DB](https://github.com/derailed/popeye/blob/master/internal/db/db.go): `internal/db/db.go`

### Lint and findings

- [Resource scrubbers](https://github.com/derailed/popeye/tree/master/internal/scrub): `internal/scrub`
- [Resource linters](https://github.com/derailed/popeye/blob/master/internal/lint/pod.go): `internal/lint/pod.go`
- [Cilium policy lint](https://github.com/derailed/popeye/blob/master/internal/cilium/lint/ccnp.go): `internal/cilium/lint/ccnp.go`
- [Finding collection](https://github.com/derailed/popeye/blob/master/internal/issues/collector.go): `internal/issues/collector.go`

### Reports and metrics

- [Report builder](https://github.com/derailed/popeye/blob/master/internal/report/builder.go): `internal/report/builder.go`
- [Report output](https://github.com/derailed/popeye/blob/master/internal/report/writer.go): `internal/report/writer.go`
- [Prometheus metrics](https://github.com/derailed/popeye/blob/master/internal/report/prometheus.go): `internal/report/prometheus.go`

### Other components

- **Operator**
- **Kubernetes cluster**

## Connections

- Operator → Program entry: invokes (evidence: `main.go`)
- Program entry → CLI commands: dispatches (evidence: `main.go`)
- CLI commands → Scan coordinator: starts scan (evidence: `cmd/root.go`)
- CLI commands → Scan configuration: sets flags (evidence: `cmd/root.go`)
- Scan coordinator → Scan configuration: loads config (evidence: `pkg/popeye.go`)
- Scan coordinator → Kubernetes client: initializes client (evidence: `pkg/popeye.go`)
- Kubernetes client → Kubernetes cluster: queries API (evidence: `internal/client/client.go`)
- Scan coordinator → Resource factory: creates factory (evidence: `pkg/popeye.go`)
- Resource factory → Kubernetes cluster: reads resources
- Scan coordinator → In-memory resource DB: initializes DB (evidence: `pkg/popeye.go`)
- Resource loader → In-memory resource DB: loads resources (evidence: `internal/db/loader.go`)
- Scan coordinator → Resource linters: runs lint (evidence: `pkg/popeye.go`)
- Resource linters → In-memory resource DB: reads resources (evidence: `internal/lint/pod.go`)
- Resource linters → Finding collection: records findings (evidence: `internal/lint/pod.go`)
- Scan coordinator → Report builder: adds outcomes (evidence: `pkg/popeye.go`)
- Report builder → Report output: formats report (evidence: `internal/report/writer.go`)
- Report builder → Prometheus metrics: publishes metrics
- Scan coordinator → Cilium policy lint: runs lint
- Resource scrubbers → In-memory resource DB: uses resource DB