# woonyong-choi/k8s-clue architecture

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

- Interactive diagram: https://gitdiagram.com/woonyong-choi/k8s-clue
- Repository: https://github.com/woonyong-choi/k8s-clue

## Overview

K8s Clue is a Kubernetes incident-diagnosis system: a read-only cluster agent gathers evidence, RCA workers identify causes and prepare bounded recovery proposals, and GitOps workers can offer those proposals as GitHub Draft PRs for human review. After a signed merge webhook, feedback workers verify recovery against later evidence. An event-driven runtime coordinates the services, while domain repositories persist incidents, evidence, inventory, and related state. The README documents an operational data catalog and user-facing incident views too; some links below reflect that documentation rather than sampled implementation calls.

Main entry points: [`src/services/ai/rca-worker/app.py`](https://github.com/woonyong-choi/k8s-clue/blob/main/src/services/ai/rca-worker/app.py) (RCA worker), [`src/services/ai/rca-feedback-worker/app.py`](https://github.com/woonyong-choi/k8s-clue/blob/main/src/services/ai/rca-feedback-worker/app.py) (Recovery verification), [`src/services/gitops/safe-pr-worker/app.py`](https://github.com/woonyong-choi/k8s-clue/blob/main/src/services/gitops/safe-pr-worker/app.py) (Safe PR worker), [`src/packages/runtime/worker.py`](https://github.com/woonyong-choi/k8s-clue/blob/main/src/packages/runtime/worker.py) (Worker runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Evidence collection"]
  node_agent["Cluster agent<br/>[agent.py]"]
  node_gateway["API gateway<br/>[app.py]"]
  node_evidence["Evidence worker<br/>[app.py]"]
end

subgraph group_analysis["RCA and recovery"]
  node_incident["Incident worker<br/>[app.py]"]
  node_rca["RCA worker<br/>[app.py]"]
  node_cause["Cause rules<br/>[engine.py]"]
  node_recovery["Recovery planning<br/>[engine.py]"]
  node_feedback["Recovery verification<br/>[app.py]"]
end

subgraph group_gitops["GitOps proposals"]
  node_safepr["Safe PR worker<br/>[app.py]"]
  node_patch["Manifest patching<br/>[source_patch.py]"]
  node_scm["SCM worker<br/>[app.py]"]
end

subgraph group_platform["Runtime and data"]
  node_postgres[("PostgreSQL")]
  node_bus["Event bus<br/>[bus.py]"]
  node_worker["Worker runtime<br/>[worker.py]"]
  node_controller["Controller runtime<br/>[controller.py]"]
  node_storage["Domain storage<br/>[engine.py]"]
end

subgraph group_product["Catalog and views"]
  node_inventory["Inventory domain<br/>[repository.py]"]
  node_catalog["Data catalog<br/>[pipeline.py]"]
  node_catalogapi["Catalog API<br/>[router.py]"]
  node_web["Incident UI<br/>[IncidentsPage.tsx]"]
  node_rcaquery["RCA query API<br/>[query_router.py]"]
end

node_k8s(("Kubernetes API"))
node_github(("GitHub App"))
node_reviewer(("Human reviewer"))

node_k8s -->|"read evidence"| node_agent
node_agent -->|"send bundle"| node_gateway
node_gateway -->|"persist evidence"| node_postgres
node_postgres -->|"deliver events"| node_rca
node_evidence -->|"publish events"| node_bus
node_incident -.->|"publish events"| node_bus
node_rca -->|"evaluate causes"| node_cause
node_cause -->|"plan recovery"| node_recovery
node_rca -->|"send cause proposal"| node_safepr
node_safepr -.->|"build patch"| node_patch
node_safepr -->|"send patch proposal"| node_scm
node_scm -->|"create draft PR"| node_github
node_github -->|"request review"| node_reviewer
node_reviewer -->|"merge decision"| node_github
node_github -->|"send merge webhook"| node_feedback
node_feedback -->|"record verification"| node_postgres
node_feedback -.->|"compare new evidence"| node_agent
node_controller -->|"starts services"| node_worker
node_worker -->|"consumes events"| node_bus
node_worker -->|"records processing"| node_storage
node_storage -.->|"uses database"| node_postgres
node_inventory -.->|"uses database"| node_storage
node_catalog -.->|"serves catalog"| node_catalogapi
node_web -.->|"loads incident data"| node_rcaquery

click node_agent "https://github.com/woonyong-choi/k8s-clue/blob/main/src/services/target/cluster-agent/agent.py"
click node_gateway "https://github.com/woonyong-choi/k8s-clue/blob/main/src/services/gateway/api-gateway/app.py"
click node_evidence "https://github.com/woonyong-choi/k8s-clue/blob/main/src/services/ai/evidence-worker/app.py"
click node_incident "https://github.com/woonyong-choi/k8s-clue/blob/main/src/services/ai/incident-worker/app.py"
click node_rca "https://github.com/woonyong-choi/k8s-clue/blob/main/src/services/ai/rca-worker/app.py"
click node_cause "https://github.com/woonyong-choi/k8s-clue/blob/main/src/services/ai/agent/causes/engine.py"
click node_recovery "https://github.com/woonyong-choi/k8s-clue/blob/main/src/services/ai/agent/recovery/engine.py"
click node_feedback "https://github.com/woonyong-choi/k8s-clue/blob/main/src/services/ai/rca-feedback-worker/app.py"
click node_safepr "https://github.com/woonyong-choi/k8s-clue/blob/main/src/services/gitops/safe-pr-worker/app.py"
click node_patch "https://github.com/woonyong-choi/k8s-clue/blob/main/src/domains/gitops/source_patch.py"
click node_scm "https://github.com/woonyong-choi/k8s-clue/blob/main/src/services/gitops/scm-worker/app.py"
click node_bus "https://github.com/woonyong-choi/k8s-clue/blob/main/src/packages/events/bus.py"
click node_worker "https://github.com/woonyong-choi/k8s-clue/blob/main/src/packages/runtime/worker.py"
click node_controller "https://github.com/woonyong-choi/k8s-clue/blob/main/src/packages/runtime/controller.py"
click node_storage "https://github.com/woonyong-choi/k8s-clue/blob/main/src/packages/storage/engine.py"
click node_inventory "https://github.com/woonyong-choi/k8s-clue/blob/main/src/domains/inventory/repository.py"
click node_catalog "https://github.com/woonyong-choi/k8s-clue/blob/main/src/domains/datacatalog/pipeline.py"
click node_catalogapi "https://github.com/woonyong-choi/k8s-clue/blob/main/src/domains/datacatalog/router.py"
click node_web "https://github.com/woonyong-choi/k8s-clue/blob/main/frontend/src/pages/IncidentsPage.tsx"
click node_rcaquery "https://github.com/woonyong-choi/k8s-clue/blob/main/src/domains/rca/query_router.py"

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_agent,node_gateway,node_evidence,node_reviewer toneBlue
class node_incident,node_rca,node_cause,node_recovery,node_feedback toneAmber
class node_safepr,node_patch,node_scm,node_k8s toneMint
class node_postgres,node_bus,node_worker,node_controller,node_storage toneRose
class node_inventory,node_catalog,node_catalogapi,node_web,node_rcaquery,node_github toneIndigo
```

## Components

### Evidence collection

- [Cluster agent](https://github.com/woonyong-choi/k8s-clue/blob/main/src/services/target/cluster-agent/agent.py): `src/services/target/cluster-agent/agent.py`
- [API gateway](https://github.com/woonyong-choi/k8s-clue/blob/main/src/services/gateway/api-gateway/app.py): `src/services/gateway/api-gateway/app.py`
- [Evidence worker](https://github.com/woonyong-choi/k8s-clue/blob/main/src/services/ai/evidence-worker/app.py): `src/services/ai/evidence-worker/app.py`

### RCA and recovery

- [Incident worker](https://github.com/woonyong-choi/k8s-clue/blob/main/src/services/ai/incident-worker/app.py): `src/services/ai/incident-worker/app.py`
- [RCA worker](https://github.com/woonyong-choi/k8s-clue/blob/main/src/services/ai/rca-worker/app.py): `src/services/ai/rca-worker/app.py`
- [Cause rules](https://github.com/woonyong-choi/k8s-clue/blob/main/src/services/ai/agent/causes/engine.py): `src/services/ai/agent/causes/engine.py`
- [Recovery planning](https://github.com/woonyong-choi/k8s-clue/blob/main/src/services/ai/agent/recovery/engine.py): `src/services/ai/agent/recovery/engine.py`
- [Recovery verification](https://github.com/woonyong-choi/k8s-clue/blob/main/src/services/ai/rca-feedback-worker/app.py): `src/services/ai/rca-feedback-worker/app.py`

### GitOps proposals

- [Safe PR worker](https://github.com/woonyong-choi/k8s-clue/blob/main/src/services/gitops/safe-pr-worker/app.py): `src/services/gitops/safe-pr-worker/app.py`
- [Manifest patching](https://github.com/woonyong-choi/k8s-clue/blob/main/src/domains/gitops/source_patch.py): `src/domains/gitops/source_patch.py`
- [SCM worker](https://github.com/woonyong-choi/k8s-clue/blob/main/src/services/gitops/scm-worker/app.py): `src/services/gitops/scm-worker/app.py`

### Runtime and data

- **PostgreSQL**
- [Event bus](https://github.com/woonyong-choi/k8s-clue/blob/main/src/packages/events/bus.py): `src/packages/events/bus.py`
- [Worker runtime](https://github.com/woonyong-choi/k8s-clue/blob/main/src/packages/runtime/worker.py): `src/packages/runtime/worker.py`
- [Controller runtime](https://github.com/woonyong-choi/k8s-clue/blob/main/src/packages/runtime/controller.py): `src/packages/runtime/controller.py`
- [Domain storage](https://github.com/woonyong-choi/k8s-clue/blob/main/src/packages/storage/engine.py): `src/packages/storage/engine.py`

### Catalog and views

- [Inventory domain](https://github.com/woonyong-choi/k8s-clue/blob/main/src/domains/inventory/repository.py): `src/domains/inventory/repository.py`
- [Data catalog](https://github.com/woonyong-choi/k8s-clue/blob/main/src/domains/datacatalog/pipeline.py): `src/domains/datacatalog/pipeline.py`
- [Catalog API](https://github.com/woonyong-choi/k8s-clue/blob/main/src/domains/datacatalog/router.py): `src/domains/datacatalog/router.py`
- [Incident UI](https://github.com/woonyong-choi/k8s-clue/blob/main/frontend/src/pages/IncidentsPage.tsx): `frontend/src/pages/IncidentsPage.tsx`
- [RCA query API](https://github.com/woonyong-choi/k8s-clue/blob/main/src/domains/rca/query_router.py): `src/domains/rca/query_router.py`

### Other components

- **Kubernetes API**
- **GitHub App**
- **Human reviewer**

## Connections

- Kubernetes API → Cluster agent: read evidence (evidence: `README.md`)
- Cluster agent → API gateway: send bundle (evidence: `README.md`)
- API gateway → PostgreSQL: persist evidence (evidence: `README.md`)
- PostgreSQL → RCA worker: deliver events (evidence: `README.md`)
- Evidence worker → Event bus: publish events (evidence: `src/services/ai/evidence-worker/app.py`)
- Incident worker → Event bus: publish events
- RCA worker → Cause rules: evaluate causes (evidence: `src/services/ai/agent/causes/engine.py`)
- Cause rules → Recovery planning: plan recovery
- RCA worker → Safe PR worker: send cause proposal (evidence: `README.md`)
- Safe PR worker → Manifest patching: build patch
- Safe PR worker → SCM worker: send patch proposal (evidence: `README.md`)
- SCM worker → GitHub App: create draft PR (evidence: `README.md`)
- GitHub App → Human reviewer: request review (evidence: `README.md`)
- Human reviewer → GitHub App: merge decision (evidence: `README.md`)
- GitHub App → Recovery verification: send merge webhook (evidence: `README.md`)
- Recovery verification → PostgreSQL: record verification (evidence: `README.md`)
- Recovery verification → Cluster agent: compare new evidence
- Controller runtime → Worker runtime: starts services (evidence: `src/packages/runtime/controller.py`)
- Worker runtime → Event bus: consumes events (evidence: `src/packages/runtime/worker.py`)
- Worker runtime → Domain storage: records processing (evidence: `src/packages/runtime/worker.py`)
- Domain storage → PostgreSQL: uses database
- Inventory domain → Domain storage: uses database (evidence: `src/domains/inventory/repository.py`)
- Data catalog → Catalog API: serves catalog
- Incident UI → RCA query API: loads incident data
