# marcocristofolini/ai-sre-rca architecture

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

- Interactive diagram: https://gitdiagram.com/marcocristofolini/ai-sre-rca
- Repository: https://github.com/marcocristofolini/ai-sre-rca

## Overview

AI SRE RCA is a read-only incident investigation service: Alertmanager or API incidents enter the backend, which gathers infrastructure, observability, change, trace, and dependency evidence before returning a structured, evidence-backed RCA. The graph preserves the distinct Kubernetes, trace, and stateful-diagnosis stages, plus memory, access controls, operational reporting, and UI paths. README documents several capabilities whose detailed wiring was not sampled; those subsystems are included where paths are supported, while uncertain internal links are omitted.

Main entry points: [`backend/app/core/engine.py`](https://github.com/marcocristofolini/ai-sre-rca/blob/main/backend/app/core/engine.py) (Investigation engine), [`frontend/lib/api.ts`](https://github.com/marcocristofolini/ai-sre-rca/blob/main/frontend/lib/api.ts) (Frontend API client), [`backend/app/api/incidents.py`](https://github.com/marcocristofolini/ai-sre-rca/blob/main/backend/app/api/incidents.py) (Incident API), [`backend/app/operations.py`](https://github.com/marcocristofolini/ai-sre-rca/blob/main/backend/app/operations.py) (Persistence and delivery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and access"]
  node_incidents_api["Incident API<br/>[incidents.py]"]
  node_webhook_api["Alert webhook<br/>[webhooks.py]"]
  node_system_api["System API<br/>[system.py]"]
  node_auth["OIDC and RBAC<br/>[auth.py]"]
end

subgraph group_investigation["Investigation"]
  node_engine["Investigation engine<br/>[engine.py]"]
  node_playbooks["Kubernetes playbooks<br/>[playbooks.py]"]
  node_trace["Trace analysis<br/>[trace_analysis.py]"]
  node_stateful["Dependency RCA"]
  node_scoring["Hypothesis scoring<br/>[scoring.py]"]
  node_llm["LLM proposer<br/>[hypotheses.py]"]
end

subgraph group_integrations["Evidence sources"]
  node_integrations["Read-only integrations"]
end

subgraph group_state["Memory and operations"]
  node_memory[("Incident memory<br/>[repository.py]")]
  node_audit[("Audit and retention<br/>[repository.py]")]
  node_operations["Persistence and delivery<br/>[operations.py]"]
  node_notifications["Slack and PagerDuty<br/>[notifications.py]"]
end

subgraph group_presentation["User experience"]
  node_ops_ui["Operations UI<br/>[page.tsx]"]
  node_web_ui["Investigation UI"]
  node_api_client["Frontend API client<br/>[api.ts]"]
  node_stateful_ui["Stateful demo pages"]
  node_trace_ui["Trace page<br/>[page.tsx]"]
end

node_alertmanager(("Alertmanager"))
node_api_user(("API user"))
node_kubernetes["Kubernetes"]
node_telemetry["Prometheus, Loki, Tempo"]
node_changes["Argo CD, GitHub, Karpenter"]

node_alertmanager -->|"posts alerts"| node_webhook_api
node_api_user -->|"submits or reads"| node_incidents_api
node_incidents_api -->|"authorizes"| node_auth
node_webhook_api -->|"investigates"| node_engine
node_webhook_api -->|"audits and persists"| node_operations
node_incidents_api -->|"investigates"| node_engine
node_incidents_api -->|"persists results"| node_operations
node_system_api -->|"identifies caller"| node_auth
node_engine -->|"evaluates signals"| node_playbooks
node_engine -->|"analyzes traces"| node_trace
node_engine -->|"investigates dependencies"| node_stateful
node_engine -->|"queries evidence"| node_integrations
node_integrations -->|"reads cluster state"| node_kubernetes
node_integrations -->|"queries telemetry"| node_telemetry
node_integrations -->|"reads change data"| node_changes
node_engine -->|"retrieves similar incidents"| node_memory
node_engine -->|"evaluates hypotheses"| node_scoring
node_engine -.->|"requests proposals"| node_llm
node_operations -->|"saves investigations"| node_memory
node_operations -->|"appends audit events"| node_audit
node_operations -->|"dispatches alerts"| node_notifications
node_api_user -->|"views results"| node_web_ui
node_web_ui -->|"loads investigation"| node_api_client
node_api_client -->|"fetches incident"| node_incidents_api
node_stateful_ui -->|"loads demo data"| node_api_client
node_trace_ui -->|"loads trace data"| node_api_client
node_ops_ui -->|"loads system status"| node_api_client
node_api_client -->|"fetches identity"| node_system_api

click node_incidents_api "https://github.com/marcocristofolini/ai-sre-rca/blob/main/backend/app/api/incidents.py"
click node_webhook_api "https://github.com/marcocristofolini/ai-sre-rca/blob/main/backend/app/api/webhooks.py"
click node_system_api "https://github.com/marcocristofolini/ai-sre-rca/blob/main/backend/app/api/system.py"
click node_auth "https://github.com/marcocristofolini/ai-sre-rca/blob/main/backend/app/auth.py"
click node_engine "https://github.com/marcocristofolini/ai-sre-rca/blob/main/backend/app/core/engine.py"
click node_playbooks "https://github.com/marcocristofolini/ai-sre-rca/blob/main/backend/app/core/playbooks.py"
click node_trace "https://github.com/marcocristofolini/ai-sre-rca/blob/main/backend/app/core/trace_analysis.py"
click node_stateful "https://github.com/marcocristofolini/ai-sre-rca/blob/main/backend/app/core/stateful_dependency.py"
click node_scoring "https://github.com/marcocristofolini/ai-sre-rca/blob/main/backend/app/core/scoring.py"
click node_llm "https://github.com/marcocristofolini/ai-sre-rca/blob/main/backend/app/llm/hypotheses.py"
click node_integrations "https://github.com/marcocristofolini/ai-sre-rca/tree/main/backend/app/integrations"
click node_memory "https://github.com/marcocristofolini/ai-sre-rca/blob/main/backend/app/db/repository.py"
click node_audit "https://github.com/marcocristofolini/ai-sre-rca/blob/main/backend/app/db/repository.py"
click node_operations "https://github.com/marcocristofolini/ai-sre-rca/blob/main/backend/app/operations.py"
click node_notifications "https://github.com/marcocristofolini/ai-sre-rca/blob/main/backend/app/notifications.py"
click node_ops_ui "https://github.com/marcocristofolini/ai-sre-rca/blob/main/frontend/app/ops/page.tsx"
click node_web_ui "https://github.com/marcocristofolini/ai-sre-rca/blob/main/frontend/components/InvestigationView.tsx"
click node_api_client "https://github.com/marcocristofolini/ai-sre-rca/blob/main/frontend/lib/api.ts"
click node_stateful_ui "https://github.com/marcocristofolini/ai-sre-rca/tree/main/frontend/app/stateful"
click node_trace_ui "https://github.com/marcocristofolini/ai-sre-rca/blob/main/frontend/app/trace/page.tsx"

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_incidents_api,node_webhook_api,node_system_api,node_auth,node_api_user toneBlue
class node_engine,node_playbooks,node_trace,node_stateful,node_scoring,node_llm toneAmber
class node_integrations toneMint
class node_memory,node_audit,node_operations,node_notifications toneRose
class node_ops_ui,node_web_ui,node_api_client,node_stateful_ui,node_trace_ui,node_alertmanager,node_kubernetes,node_telemetry,node_changes toneIndigo
```

## Components

### Entry and access

- [Incident API](https://github.com/marcocristofolini/ai-sre-rca/blob/main/backend/app/api/incidents.py): `backend/app/api/incidents.py`
- [Alert webhook](https://github.com/marcocristofolini/ai-sre-rca/blob/main/backend/app/api/webhooks.py): `backend/app/api/webhooks.py`
- [System API](https://github.com/marcocristofolini/ai-sre-rca/blob/main/backend/app/api/system.py): `backend/app/api/system.py`
- [OIDC and RBAC](https://github.com/marcocristofolini/ai-sre-rca/blob/main/backend/app/auth.py): `backend/app/auth.py`

### Investigation

- [Investigation engine](https://github.com/marcocristofolini/ai-sre-rca/blob/main/backend/app/core/engine.py): `backend/app/core/engine.py`
- [Kubernetes playbooks](https://github.com/marcocristofolini/ai-sre-rca/blob/main/backend/app/core/playbooks.py): `backend/app/core/playbooks.py`
- [Trace analysis](https://github.com/marcocristofolini/ai-sre-rca/blob/main/backend/app/core/trace_analysis.py): `backend/app/core/trace_analysis.py`
- [Dependency RCA](https://github.com/marcocristofolini/ai-sre-rca/blob/main/backend/app/core/stateful_dependency.py): `backend/app/core/stateful_dependency.py`
- [Hypothesis scoring](https://github.com/marcocristofolini/ai-sre-rca/blob/main/backend/app/core/scoring.py): `backend/app/core/scoring.py`
- [LLM proposer](https://github.com/marcocristofolini/ai-sre-rca/blob/main/backend/app/llm/hypotheses.py): `backend/app/llm/hypotheses.py`

### Evidence sources

- [Read-only integrations](https://github.com/marcocristofolini/ai-sre-rca/tree/main/backend/app/integrations): `backend/app/integrations`

### Memory and operations

- [Incident memory](https://github.com/marcocristofolini/ai-sre-rca/blob/main/backend/app/db/repository.py): `backend/app/db/repository.py`
- [Audit and retention](https://github.com/marcocristofolini/ai-sre-rca/blob/main/backend/app/db/repository.py): `backend/app/db/repository.py`
- [Persistence and delivery](https://github.com/marcocristofolini/ai-sre-rca/blob/main/backend/app/operations.py): `backend/app/operations.py`
- [Slack and PagerDuty](https://github.com/marcocristofolini/ai-sre-rca/blob/main/backend/app/notifications.py): `backend/app/notifications.py`

### User experience

- [Operations UI](https://github.com/marcocristofolini/ai-sre-rca/blob/main/frontend/app/ops/page.tsx): `frontend/app/ops/page.tsx`
- [Investigation UI](https://github.com/marcocristofolini/ai-sre-rca/blob/main/frontend/components/InvestigationView.tsx): `frontend/components/InvestigationView.tsx`
- [Frontend API client](https://github.com/marcocristofolini/ai-sre-rca/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`
- [Stateful demo pages](https://github.com/marcocristofolini/ai-sre-rca/tree/main/frontend/app/stateful): `frontend/app/stateful`
- [Trace page](https://github.com/marcocristofolini/ai-sre-rca/blob/main/frontend/app/trace/page.tsx): `frontend/app/trace/page.tsx`

### Other components

- **Alertmanager**
- **API user**
- **Kubernetes**
- **Prometheus, Loki, Tempo**
- **Argo CD, GitHub, Karpenter**

## Connections

- Alertmanager → Alert webhook: posts alerts
- API user → Incident API: submits or reads
- Incident API → OIDC and RBAC: authorizes
- Alert webhook → Investigation engine: investigates
- Alert webhook → Persistence and delivery: audits and persists
- Incident API → Investigation engine: investigates
- Incident API → Persistence and delivery: persists results
- System API → OIDC and RBAC: identifies caller
- Investigation engine → Kubernetes playbooks: evaluates signals
- Investigation engine → Trace analysis: analyzes traces
- Investigation engine → Dependency RCA: investigates dependencies
- Investigation engine → Read-only integrations: queries evidence
- Read-only integrations → Kubernetes: reads cluster state
- Read-only integrations → Prometheus, Loki, Tempo: queries telemetry
- Read-only integrations → Argo CD, GitHub, Karpenter: reads change data
- Investigation engine → Incident memory: retrieves similar incidents
- Investigation engine → Hypothesis scoring: evaluates hypotheses
- Investigation engine → LLM proposer: requests proposals
- Persistence and delivery → Incident memory: saves investigations
- Persistence and delivery → Audit and retention: appends audit events
- Persistence and delivery → Slack and PagerDuty: dispatches alerts
- API user → Investigation UI: views results
- Investigation UI → Frontend API client: loads investigation
- Frontend API client → Incident API: fetches incident
- Stateful demo pages → Frontend API client: loads demo data
- Trace page → Frontend API client: loads trace data
- Operations UI → Frontend API client: loads system status
- Frontend API client → System API: fetches identity