# versuscontrol/versus-incident architecture

> Architecture diagram of the GitHub repository versuscontrol/versus-incident, 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/versuscontrol/versus-incident
- Repository: https://github.com/versuscontrol/versus-incident

## Overview

Versus Incident is a self-hosted incident-response product: incidents arrive from either the AI SRE agent or inbound webhooks, then share incident handling, notifications, templates, and on-call escalation. The dashboard supports incident response and agent administration, with additional service-health, topology, Kubernetes, chat, and runbook capabilities. The main evidence here is README documentation, the route setup, startup wiring, and selected agent and manager excerpts; links for unsampled subsystems are included only where documented, and some runtime details remain unverified.

Main entry points: [`pkg/agent/worker.go`](https://github.com/versuscontrol/versus-incident/blob/main/pkg/agent/worker.go) (Agent Worker), [`pkg/routes/routes.go`](https://github.com/versuscontrol/versus-incident/blob/main/pkg/routes/routes.go) (HTTP Routes), [`pkg/services/incident.go`](https://github.com/versuscontrol/versus-incident/blob/main/pkg/services/incident.go) (Incident Handling), [`ui/src/App.tsx`](https://github.com/versuscontrol/versus-incident/blob/main/ui/src/App.tsx) (Admin Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Incident Ingestion"]
  node_webhook["Webhook Intake<br/>[incident.go]"]
end

subgraph group_agent["AI SRE Agent"]
  node_signalread["Signal Readers"]
  node_worker["Agent Worker<br/>[worker.go]"]
  node_learning["Pattern Learning<br/>[miner.go]"]
  node_catalog[("Pattern Catalog<br/>[catalog.go]")]
  node_triage["AI Triage<br/>[agent.go]"]
  node_runbooks[("Runbook Search<br/>[manager.go]")]
  node_metrics["Metrics and Traces<br/>[query_metrics.go]"]
end

subgraph group_response["Incident Response"]
  node_incident["Incident Handling<br/>[incident.go]"]
  node_storage[("Incident Storage<br/>[storage.go]")]
  node_notify["Channels and On-Call<br/>[factory_alert.go]"]
end

subgraph group_insights["Operations Insights"]
  node_servicehealth[("Service Health<br/>[manager.go]")]
  node_topology["Service Topology<br/>[manager.go]"]
  node_kubernetes["Kubernetes Operations<br/>[service.go]"]
end

subgraph group_console["Admin Console"]
  node_routes["HTTP Routes<br/>[routes.go]"]
  node_dashboard["Admin Dashboard<br/>[App.tsx]"]
  node_api["Dashboard API Client<br/>[api.ts]"]
  node_opsviews["Operations Views"]
  node_chat["AI Chat<br/>[service.go]"]
end

node_operator(("SRE Operator"))
node_monitor(("Alerting Systems"))
node_source{{"Log Sources"}}

node_source -.->|"provides logs"| node_signalread
node_signalread -.->|"yields signals"| node_worker
node_worker -.->|"learns patterns"| node_learning
node_worker -->|"uses catalog"| node_catalog
node_worker -.->|"requests triage"| node_triage
node_worker -.->|"raises incidents"| node_incident
node_monitor -->|"posts alerts"| node_webhook
node_routes -->|"mounts intake"| node_webhook
node_webhook -.->|"creates incident"| node_incident
node_incident -.->|"persists history"| node_storage
node_incident -.->|"fans out"| node_notify
node_notify -.->|"notifies"| node_operator
node_operator -.->|"uses console"| node_dashboard
node_dashboard -->|"routes views"| node_opsviews
node_dashboard -.->|"uses API"| node_api
node_routes -->|"registers endpoints"| node_servicehealth
node_routes -->|"registers endpoints"| node_topology
node_routes -.->|"registers endpoints"| node_chat
node_worker -.->|"searches runbooks"| node_runbooks
node_worker -.->|"queries telemetry"| node_metrics
node_opsviews -.->|"administers"| node_kubernetes

click node_signalread "https://github.com/versuscontrol/versus-incident/tree/main/pkg/signalsources"
click node_worker "https://github.com/versuscontrol/versus-incident/blob/main/pkg/agent/worker.go"
click node_learning "https://github.com/versuscontrol/versus-incident/blob/main/pkg/agent/miner.go"
click node_catalog "https://github.com/versuscontrol/versus-incident/blob/main/pkg/agent/catalog.go"
click node_triage "https://github.com/versuscontrol/versus-incident/blob/main/pkg/agent/ai/analyze/agent.go"
click node_webhook "https://github.com/versuscontrol/versus-incident/blob/main/pkg/controllers/incident.go"
click node_incident "https://github.com/versuscontrol/versus-incident/blob/main/pkg/services/incident.go"
click node_storage "https://github.com/versuscontrol/versus-incident/blob/main/pkg/storage/storage.go"
click node_notify "https://github.com/versuscontrol/versus-incident/blob/main/pkg/common/factory_alert.go"
click node_routes "https://github.com/versuscontrol/versus-incident/blob/main/pkg/routes/routes.go"
click node_dashboard "https://github.com/versuscontrol/versus-incident/blob/main/ui/src/App.tsx"
click node_api "https://github.com/versuscontrol/versus-incident/blob/main/ui/src/lib/api.ts"
click node_opsviews "https://github.com/versuscontrol/versus-incident/tree/main/ui/src/pages"
click node_chat "https://github.com/versuscontrol/versus-incident/blob/main/pkg/agent/ai/chat/service.go"
click node_runbooks "https://github.com/versuscontrol/versus-incident/blob/main/pkg/runbook/manager.go"
click node_servicehealth "https://github.com/versuscontrol/versus-incident/blob/main/pkg/servicehealth/manager.go"
click node_topology "https://github.com/versuscontrol/versus-incident/blob/main/pkg/servicetopology/manager.go"
click node_kubernetes "https://github.com/versuscontrol/versus-incident/blob/main/pkg/kubernetes/service.go"
click node_metrics "https://github.com/versuscontrol/versus-incident/blob/main/pkg/agent/ai/tools/common/query_metrics.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_webhook toneBlue
class node_signalread,node_worker,node_learning,node_catalog,node_triage,node_runbooks,node_metrics toneAmber
class node_incident,node_storage,node_notify toneMint
class node_servicehealth,node_topology,node_kubernetes toneRose
class node_routes,node_dashboard,node_api,node_opsviews,node_chat,node_operator,node_monitor,node_source toneIndigo
```

## Components

### Incident Ingestion

- [Webhook Intake](https://github.com/versuscontrol/versus-incident/blob/main/pkg/controllers/incident.go): `pkg/controllers/incident.go`

### AI SRE Agent

- [Signal Readers](https://github.com/versuscontrol/versus-incident/tree/main/pkg/signalsources): `pkg/signalsources`
- [Agent Worker](https://github.com/versuscontrol/versus-incident/blob/main/pkg/agent/worker.go): `pkg/agent/worker.go`
- [Pattern Learning](https://github.com/versuscontrol/versus-incident/blob/main/pkg/agent/miner.go): `pkg/agent/miner.go`
- [Pattern Catalog](https://github.com/versuscontrol/versus-incident/blob/main/pkg/agent/catalog.go): `pkg/agent/catalog.go`
- [AI Triage](https://github.com/versuscontrol/versus-incident/blob/main/pkg/agent/ai/analyze/agent.go): `pkg/agent/ai/analyze/agent.go`
- [Runbook Search](https://github.com/versuscontrol/versus-incident/blob/main/pkg/runbook/manager.go): `pkg/runbook/manager.go`
- [Metrics and Traces](https://github.com/versuscontrol/versus-incident/blob/main/pkg/agent/ai/tools/common/query_metrics.go): `pkg/agent/ai/tools/common/query_metrics.go`

### Incident Response

- [Incident Handling](https://github.com/versuscontrol/versus-incident/blob/main/pkg/services/incident.go): `pkg/services/incident.go`
- [Incident Storage](https://github.com/versuscontrol/versus-incident/blob/main/pkg/storage/storage.go): `pkg/storage/storage.go`
- [Channels and On-Call](https://github.com/versuscontrol/versus-incident/blob/main/pkg/common/factory_alert.go): `pkg/common/factory_alert.go`

### Operations Insights

- [Service Health](https://github.com/versuscontrol/versus-incident/blob/main/pkg/servicehealth/manager.go): `pkg/servicehealth/manager.go`
- [Service Topology](https://github.com/versuscontrol/versus-incident/blob/main/pkg/servicetopology/manager.go): `pkg/servicetopology/manager.go`
- [Kubernetes Operations](https://github.com/versuscontrol/versus-incident/blob/main/pkg/kubernetes/service.go): `pkg/kubernetes/service.go`

### Admin Console

- [HTTP Routes](https://github.com/versuscontrol/versus-incident/blob/main/pkg/routes/routes.go): `pkg/routes/routes.go`
- [Admin Dashboard](https://github.com/versuscontrol/versus-incident/blob/main/ui/src/App.tsx): `ui/src/App.tsx`
- [Dashboard API Client](https://github.com/versuscontrol/versus-incident/blob/main/ui/src/lib/api.ts): `ui/src/lib/api.ts`
- [Operations Views](https://github.com/versuscontrol/versus-incident/tree/main/ui/src/pages): `ui/src/pages`
- [AI Chat](https://github.com/versuscontrol/versus-incident/blob/main/pkg/agent/ai/chat/service.go): `pkg/agent/ai/chat/service.go`

### Other components

- **SRE Operator**
- **Alerting Systems**
- **Log Sources**

## Connections

- Log Sources → Signal Readers: provides logs
- Signal Readers → Agent Worker: yields signals (evidence: `pkg/agent/worker.go`)
- Agent Worker → Pattern Learning: learns patterns
- Agent Worker → Pattern Catalog: uses catalog (evidence: `pkg/agent/worker.go`)
- Agent Worker → AI Triage: requests triage
- Agent Worker → Incident Handling: raises incidents
- Alerting Systems → Webhook Intake: posts alerts
- HTTP Routes → Webhook Intake: mounts intake (evidence: `pkg/routes/routes.go`)
- Webhook Intake → Incident Handling: creates incident
- Incident Handling → Incident Storage: persists history
- Incident Handling → Channels and On-Call: fans out
- Channels and On-Call → SRE Operator: notifies
- SRE Operator → Admin Dashboard: uses console
- Admin Dashboard → Operations Views: routes views (evidence: `ui/src/App.tsx`)
- Admin Dashboard → Dashboard API Client: uses API
- HTTP Routes → Service Health: registers endpoints (evidence: `pkg/routes/routes.go`)
- HTTP Routes → Service Topology: registers endpoints (evidence: `pkg/routes/routes.go`)
- HTTP Routes → AI Chat: registers endpoints (evidence: `pkg/routes/routes.go`)
- Agent Worker → Runbook Search: searches runbooks (evidence: `pkg/runbook/manager.go`)
- Agent Worker → Metrics and Traces: queries telemetry (evidence: `pkg/agent/ai/tools/common/query_metrics.go`)
- Operations Views → Kubernetes Operations: administers