# duckiec/srek3s architecture

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

- Interactive diagram: https://gitdiagram.com/duckiec/srek3s
- Repository: https://github.com/duckiec/srek3s

## Overview

SREK3S is a read-only Kubernetes incident-response agent. The principal path observes pod failures, sanitizes telemetry before egress, sends a validated incident to the Python service, and returns a deterministic triage outcome with a verified GitOps patch where safe or human escalation otherwise. The graph includes the documented verification and provider capabilities; some internal wiring is omitted where excerpts do not establish the call.

Main entry points: [`agent/triage.py`](https://github.com/duckiec/srek3s/blob/main/agent/triage.py) (Triage orchestration), [`agent/main.py`](https://github.com/duckiec/srek3s/blob/main/agent/main.py) (Triage API), [`internal/worker/pool.go`](https://github.com/duckiec/srek3s/blob/main/internal/worker/pool.go) (Incident worker pool), [`cmd/sentinel/main.go`](https://github.com/duckiec/srek3s/blob/main/cmd/sentinel/main.go) (Sentinel process)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_observe["Cluster observation"]
  node_k8s["Read-only Kubernetes access"]
  node_watcher["Pod failure watcher<br/>[watcher.go]"]
  node_worker["Incident worker pool<br/>[pool.go]"]
  node_sentinel["Sentinel process<br/>[main.go]"]
end

subgraph group_transport["Sanitize and transport"]
  node_scrubber["Secret scrubbing<br/>[scrubber.go]"]
  node_emitter["Payload and HTTP emitter<br/>[emitter.go]"]
end

subgraph group_triage["Triage and remediation"]
  node_triage["Triage orchestration<br/>[triage.py]"]
  node_classifier["Classification and routing<br/>[classifier.py]"]
  node_prompt["Evidence and rationale<br/>[prompt.py]"]
  node_budget["Analysis budget<br/>[budget.py]"]
  node_llm["Model boundary<br/>[llm.py]"]
  node_providers["Model provider adapters<br/>[providers.py]"]
  node_patch["Patch generation<br/>[patch.py]"]
  node_verify["Patch verification<br/>[verify.py]"]
  node_rescan["Output rescanning<br/>[rescan.py]"]
  node_warroom["Human escalation<br/>[warroom.py]"]
end

subgraph group_runtime["Agent runtime"]
  node_agent["Triage API<br/>[main.py]"]
  node_schemas["Incident and response schemas<br/>[models.py]"]
  node_sandbox["Jailed analysis worker<br/>[sandbox.py]"]
  node_sandbox_worker["Deterministic worker<br/>[sandbox_worker.py]"]
end

node_operator(("Cluster operator"))
node_manifest["GitOps manifest checkout"]
node_cluster[("Kubernetes cluster")]
node_model_service(("LLM service"))
node_gitops_user(("GitOps reviewer"))

node_sentinel -->|"starts watch"| node_watcher
node_sentinel -->|"starts pool"| node_worker
node_sentinel -->|"wires clients"| node_k8s
node_watcher -.->|"observes pods"| node_k8s
node_k8s -.->|"reads events"| node_cluster
node_watcher -.->|"queues incidents"| node_worker
node_worker -->|"scrubs telemetry"| node_scrubber
node_worker -->|"dispatches incident"| node_emitter
node_emitter -->|"posts payload"| node_agent
node_agent -.->|"validates contract"| node_schemas
node_agent -.->|"bounds jobs"| node_budget
node_agent -.->|"runs analysis"| node_sandbox
node_sandbox -->|"executes worker"| node_sandbox_worker
node_sandbox_worker -->|"classifies and routes"| node_classifier
node_agent -.->|"orchestrates triage"| node_triage
node_triage -->|"classifies and routes"| node_classifier
node_triage -->|"builds evidence"| node_prompt
node_triage -->|"requests analysis"| node_llm
node_llm -->|"selects transport"| node_providers
node_providers -.->|"sends prompt"| node_model_service
node_triage -.->|"generates patch"| node_patch
node_triage -.->|"verifies patch"| node_verify
node_verify -.->|"checks target bytes"| node_manifest
node_triage -->|"redacts response"| node_rescan
node_triage -->|"escalates for review"| node_warroom
node_agent -.->|"returns RCA or escalation"| node_gitops_user
node_operator -.->|"deploys agent"| node_cluster

click node_k8s "https://github.com/duckiec/srek3s/tree/main/internal/k8s"
click node_watcher "https://github.com/duckiec/srek3s/blob/main/internal/k8s/watcher.go"
click node_worker "https://github.com/duckiec/srek3s/blob/main/internal/worker/pool.go"
click node_scrubber "https://github.com/duckiec/srek3s/blob/main/internal/scrubber/scrubber.go"
click node_emitter "https://github.com/duckiec/srek3s/blob/main/internal/emitter/emitter.go"
click node_sentinel "https://github.com/duckiec/srek3s/blob/main/cmd/sentinel/main.go"
click node_agent "https://github.com/duckiec/srek3s/blob/main/agent/main.py"
click node_schemas "https://github.com/duckiec/srek3s/blob/main/agent/models.py"
click node_sandbox "https://github.com/duckiec/srek3s/blob/main/agent/sandbox.py"
click node_sandbox_worker "https://github.com/duckiec/srek3s/blob/main/agent/sandbox_worker.py"
click node_triage "https://github.com/duckiec/srek3s/blob/main/agent/triage.py"
click node_classifier "https://github.com/duckiec/srek3s/blob/main/agent/classifier.py"
click node_prompt "https://github.com/duckiec/srek3s/blob/main/agent/prompt.py"
click node_budget "https://github.com/duckiec/srek3s/blob/main/agent/budget.py"
click node_llm "https://github.com/duckiec/srek3s/blob/main/agent/llm.py"
click node_providers "https://github.com/duckiec/srek3s/blob/main/agent/providers.py"
click node_patch "https://github.com/duckiec/srek3s/blob/main/agent/patch.py"
click node_verify "https://github.com/duckiec/srek3s/blob/main/agent/verify.py"
click node_rescan "https://github.com/duckiec/srek3s/blob/main/agent/rescan.py"
click node_warroom "https://github.com/duckiec/srek3s/blob/main/agent/warroom.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_k8s,node_watcher,node_worker,node_sentinel,node_gitops_user toneBlue
class node_scrubber,node_emitter,node_cluster toneAmber
class node_triage,node_classifier,node_prompt,node_budget,node_llm,node_providers,node_patch,node_verify,node_rescan,node_warroom toneMint
class node_agent,node_schemas,node_sandbox,node_sandbox_worker toneRose
class node_operator,node_manifest,node_model_service toneIndigo
```

## Components

### Cluster observation

- [Read-only Kubernetes access](https://github.com/duckiec/srek3s/tree/main/internal/k8s): `internal/k8s`
- [Pod failure watcher](https://github.com/duckiec/srek3s/blob/main/internal/k8s/watcher.go): `internal/k8s/watcher.go`
- [Incident worker pool](https://github.com/duckiec/srek3s/blob/main/internal/worker/pool.go): `internal/worker/pool.go`
- [Sentinel process](https://github.com/duckiec/srek3s/blob/main/cmd/sentinel/main.go): `cmd/sentinel/main.go`

### Sanitize and transport

- [Secret scrubbing](https://github.com/duckiec/srek3s/blob/main/internal/scrubber/scrubber.go): `internal/scrubber/scrubber.go`
- [Payload and HTTP emitter](https://github.com/duckiec/srek3s/blob/main/internal/emitter/emitter.go): `internal/emitter/emitter.go`

### Triage and remediation

- [Triage orchestration](https://github.com/duckiec/srek3s/blob/main/agent/triage.py): `agent/triage.py`
- [Classification and routing](https://github.com/duckiec/srek3s/blob/main/agent/classifier.py): `agent/classifier.py`
- [Evidence and rationale](https://github.com/duckiec/srek3s/blob/main/agent/prompt.py): `agent/prompt.py`
- [Analysis budget](https://github.com/duckiec/srek3s/blob/main/agent/budget.py): `agent/budget.py`
- [Model boundary](https://github.com/duckiec/srek3s/blob/main/agent/llm.py): `agent/llm.py`
- [Model provider adapters](https://github.com/duckiec/srek3s/blob/main/agent/providers.py): `agent/providers.py`
- [Patch generation](https://github.com/duckiec/srek3s/blob/main/agent/patch.py): `agent/patch.py`
- [Patch verification](https://github.com/duckiec/srek3s/blob/main/agent/verify.py): `agent/verify.py`
- [Output rescanning](https://github.com/duckiec/srek3s/blob/main/agent/rescan.py): `agent/rescan.py`
- [Human escalation](https://github.com/duckiec/srek3s/blob/main/agent/warroom.py): `agent/warroom.py`

### Agent runtime

- [Triage API](https://github.com/duckiec/srek3s/blob/main/agent/main.py): `agent/main.py`
- [Incident and response schemas](https://github.com/duckiec/srek3s/blob/main/agent/models.py): `agent/models.py`
- [Jailed analysis worker](https://github.com/duckiec/srek3s/blob/main/agent/sandbox.py): `agent/sandbox.py`
- [Deterministic worker](https://github.com/duckiec/srek3s/blob/main/agent/sandbox_worker.py): `agent/sandbox_worker.py`

### Other components

- **Cluster operator**
- **GitOps manifest checkout**
- **Kubernetes cluster**
- **LLM service**
- **GitOps reviewer**

## Connections

- Sentinel process → Pod failure watcher: starts watch (evidence: `cmd/sentinel/main.go`)
- Sentinel process → Incident worker pool: starts pool (evidence: `cmd/sentinel/main.go`)
- Sentinel process → Read-only Kubernetes access: wires clients (evidence: `cmd/sentinel/main.go`)
- Pod failure watcher → Read-only Kubernetes access: observes pods
- Read-only Kubernetes access → Kubernetes cluster: reads events
- Pod failure watcher → Incident worker pool: queues incidents
- Incident worker pool → Secret scrubbing: scrubs telemetry (evidence: `internal/worker/pool.go`)
- Incident worker pool → Payload and HTTP emitter: dispatches incident (evidence: `internal/worker/pool.go`)
- Payload and HTTP emitter → Triage API: posts payload
- Triage API → Incident and response schemas: validates contract (evidence: `agent/main.py`)
- Triage API → Analysis budget: bounds jobs (evidence: `agent/main.py`)
- Triage API → Jailed analysis worker: runs analysis (evidence: `agent/main.py`)
- Jailed analysis worker → Deterministic worker: executes worker (evidence: `agent/sandbox_worker.py`)
- Deterministic worker → Classification and routing: classifies and routes (evidence: `agent/sandbox_worker.py`)
- Triage API → Triage orchestration: orchestrates triage (evidence: `agent/main.py`)
- Triage orchestration → Classification and routing: classifies and routes (evidence: `agent/triage.py`)
- Triage orchestration → Evidence and rationale: builds evidence (evidence: `agent/triage.py`)
- Triage orchestration → Model boundary: requests analysis (evidence: `agent/triage.py`)
- Model boundary → Model provider adapters: selects transport (evidence: `agent/llm.py`)
- Model provider adapters → LLM service: sends prompt
- Triage orchestration → Patch generation: generates patch (evidence: `agent/triage.py`)
- Triage orchestration → Patch verification: verifies patch
- Patch verification → GitOps manifest checkout: checks target bytes
- Triage orchestration → Output rescanning: redacts response (evidence: `agent/triage.py`)
- Triage orchestration → Human escalation: escalates for review (evidence: `agent/triage.py`)
- Triage API → GitOps reviewer: returns RCA or escalation
- Cluster operator → Kubernetes cluster: deploys agent
