# mkdirer/ai-sre-platform architecture

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

- Interactive diagram: https://gitdiagram.com/mkdirer/ai-sre-platform
- Repository: https://github.com/mkdirer/ai-sre-platform

## Overview

AI SRE Platform turns alerts into durable, evidence-grounded incident investigations, then gates rollback on human approval and verifies recovery. The main path is Alertmanager webhook → Incident API → queued worker → telemetry/deployment evidence → investigation report → approval → remediation and recovery checks; the frontend reviews incidents through the API. Knowledge retrieval and offline evaluation are additional capabilities. Connections follow the README or SOURCE INDEX references; unsampled implementation details are represented only where documented, so some internal links are omitted.

Main entry points: [`apps/incident_api/main.py`](https://github.com/mkdirer/ai-sre-platform/blob/main/apps/incident_api/main.py) (Incident API), [`packages/agents/workflow.py`](https://github.com/mkdirer/ai-sre-platform/blob/main/packages/agents/workflow.py) (Investigation workflow), [`packages/incidents/evidence_collection.py`](https://github.com/mkdirer/ai-sre-platform/blob/main/packages/incidents/evidence_collection.py) (Evidence collection), [`packages/remediation/service.py`](https://github.com/mkdirer/ai-sre-platform/blob/main/packages/remediation/service.py) (Remediation service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API and review"]
  node_api["Incident API<br/>[main.py]"]
  node_frontend["Review UI"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_incident["Incident processing"]
  node_incident_store[("Incident store<br/>[incident_store.py]")]
  node_queue["Task queue<br/>[publisher.py]"]
  node_worker["Investigator worker<br/>[celery_app.py]"]
end

subgraph group_investigation["Investigation and evidence"]
  node_collection["Evidence collection"]
  node_prometheus["Metrics adapter<br/>[prometheus.py]"]
  node_loki["Logs adapter<br/>[loki.py]"]
  node_tempo["Traces adapter<br/>[tempo.py]"]
  node_deployments["Deployment evidence<br/>[deployments.py]"]
  node_evidence_store[("Evidence store<br/>[evidence_store.py]")]
  node_workflow["Investigation workflow<br/>[workflow.py]"]
  node_provider["Model provider<br/>[provider.py]"]
  node_investigation_store[("Report store")]
end

subgraph group_knowledge["Knowledge and evaluation"]
  node_knowledge_service["Knowledge retrieval<br/>[service.py]"]
  node_embeddings["Embedding provider<br/>[embeddings.py]"]
  node_knowledge_store[("Knowledge store<br/>[knowledge_store.py]")]
  node_evals["Investigation evals<br/>[scenario.py]"]
end

subgraph group_remediation["Approval and recovery"]
  node_approval_store[("Approval store<br/>[approval_store.py]")]
  node_remediation_service["Remediation service<br/>[service.py]"]
  node_remediation_store[("Execution store")]
  node_rollback["Rollback adapter<br/>[adapter.py]"]
end

node_alertmanager(("Alertmanager"))
node_reviewer(("Reviewer"))

node_alertmanager -->|"sends alerts"| node_api
node_api -->|"persists incidents"| node_incident_store
node_api -->|"queues jobs"| node_queue
node_queue -->|"dispatches jobs"| node_worker
node_reviewer -->|"reviews incidents"| node_frontend
node_frontend -->|"requests data"| node_api_client
node_api_client -->|"calls API"| node_api
node_worker -->|"collects evidence"| node_collection
node_collection -->|"queries metrics"| node_prometheus
node_collection -->|"queries logs"| node_loki
node_collection -->|"queries traces"| node_tempo
node_collection -->|"queries deployments"| node_deployments
node_worker -->|"runs investigation"| node_workflow
node_workflow -->|"requests analysis"| node_provider
node_workflow -->|"reads evidence"| node_evidence_store
node_workflow -->|"stores reports"| node_investigation_store
node_workflow -->|"retrieves context"| node_knowledge_service
node_knowledge_service -->|"embeds text"| node_embeddings
node_knowledge_service -->|"searches knowledge"| node_knowledge_store
node_evals -->|"evaluates workflow"| node_workflow
node_api -->|"records decisions"| node_approval_store
node_api -.->|"requests approved action"| node_remediation_service
node_remediation_service -->|"claims executions"| node_remediation_store
node_remediation_service -->|"runs rollback"| node_rollback
node_remediation_service -->|"checks recovery"| node_prometheus

click node_api "https://github.com/mkdirer/ai-sre-platform/blob/main/apps/incident_api/main.py"
click node_frontend "https://github.com/mkdirer/ai-sre-platform/blob/main/apps/frontend/src/pages/IncidentListPage.tsx"
click node_api_client "https://github.com/mkdirer/ai-sre-platform/blob/main/apps/frontend/src/api/client.ts"
click node_incident_store "https://github.com/mkdirer/ai-sre-platform/blob/main/packages/persistence/incident_store.py"
click node_queue "https://github.com/mkdirer/ai-sre-platform/blob/main/packages/task_queue/publisher.py"
click node_worker "https://github.com/mkdirer/ai-sre-platform/blob/main/apps/investigator_worker/celery_app.py"
click node_collection "https://github.com/mkdirer/ai-sre-platform/blob/main/packages/incidents/evidence_collection.py"
click node_prometheus "https://github.com/mkdirer/ai-sre-platform/blob/main/packages/tools/prometheus.py"
click node_loki "https://github.com/mkdirer/ai-sre-platform/blob/main/packages/tools/loki.py"
click node_tempo "https://github.com/mkdirer/ai-sre-platform/blob/main/packages/tools/tempo.py"
click node_deployments "https://github.com/mkdirer/ai-sre-platform/blob/main/packages/tools/deployments.py"
click node_evidence_store "https://github.com/mkdirer/ai-sre-platform/blob/main/packages/persistence/evidence_store.py"
click node_workflow "https://github.com/mkdirer/ai-sre-platform/blob/main/packages/agents/workflow.py"
click node_provider "https://github.com/mkdirer/ai-sre-platform/blob/main/packages/agents/provider.py"
click node_investigation_store "https://github.com/mkdirer/ai-sre-platform/blob/main/packages/persistence/investigation_store.py"
click node_knowledge_service "https://github.com/mkdirer/ai-sre-platform/blob/main/packages/rag/service.py"
click node_embeddings "https://github.com/mkdirer/ai-sre-platform/blob/main/packages/rag/embeddings.py"
click node_knowledge_store "https://github.com/mkdirer/ai-sre-platform/blob/main/packages/persistence/knowledge_store.py"
click node_evals "https://github.com/mkdirer/ai-sre-platform/blob/main/packages/evals/scenario.py"
click node_approval_store "https://github.com/mkdirer/ai-sre-platform/blob/main/packages/persistence/approval_store.py"
click node_remediation_service "https://github.com/mkdirer/ai-sre-platform/blob/main/packages/remediation/service.py"
click node_remediation_store "https://github.com/mkdirer/ai-sre-platform/blob/main/packages/persistence/remediation_store.py"
click node_rollback "https://github.com/mkdirer/ai-sre-platform/blob/main/packages/remediation/adapter.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_api,node_frontend,node_api_client,node_reviewer toneBlue
class node_incident_store,node_queue,node_worker toneAmber
class node_collection,node_prometheus,node_loki,node_tempo,node_deployments,node_evidence_store,node_workflow,node_provider,node_investigation_store toneMint
class node_knowledge_service,node_embeddings,node_knowledge_store,node_evals toneRose
class node_approval_store,node_remediation_service,node_remediation_store,node_rollback,node_alertmanager toneIndigo
```

## Components

### API and review

- [Incident API](https://github.com/mkdirer/ai-sre-platform/blob/main/apps/incident_api/main.py): `apps/incident_api/main.py`
- [Review UI](https://github.com/mkdirer/ai-sre-platform/blob/main/apps/frontend/src/pages/IncidentListPage.tsx): `apps/frontend/src/pages/IncidentListPage.tsx`
- [API client](https://github.com/mkdirer/ai-sre-platform/blob/main/apps/frontend/src/api/client.ts): `apps/frontend/src/api/client.ts`

### Incident processing

- [Incident store](https://github.com/mkdirer/ai-sre-platform/blob/main/packages/persistence/incident_store.py): `packages/persistence/incident_store.py`
- [Task queue](https://github.com/mkdirer/ai-sre-platform/blob/main/packages/task_queue/publisher.py): `packages/task_queue/publisher.py`
- [Investigator worker](https://github.com/mkdirer/ai-sre-platform/blob/main/apps/investigator_worker/celery_app.py): `apps/investigator_worker/celery_app.py`

### Investigation and evidence

- [Evidence collection](https://github.com/mkdirer/ai-sre-platform/blob/main/packages/incidents/evidence_collection.py): `packages/incidents/evidence_collection.py`
- [Metrics adapter](https://github.com/mkdirer/ai-sre-platform/blob/main/packages/tools/prometheus.py): `packages/tools/prometheus.py`
- [Logs adapter](https://github.com/mkdirer/ai-sre-platform/blob/main/packages/tools/loki.py): `packages/tools/loki.py`
- [Traces adapter](https://github.com/mkdirer/ai-sre-platform/blob/main/packages/tools/tempo.py): `packages/tools/tempo.py`
- [Deployment evidence](https://github.com/mkdirer/ai-sre-platform/blob/main/packages/tools/deployments.py): `packages/tools/deployments.py`
- [Evidence store](https://github.com/mkdirer/ai-sre-platform/blob/main/packages/persistence/evidence_store.py): `packages/persistence/evidence_store.py`
- [Investigation workflow](https://github.com/mkdirer/ai-sre-platform/blob/main/packages/agents/workflow.py): `packages/agents/workflow.py`
- [Model provider](https://github.com/mkdirer/ai-sre-platform/blob/main/packages/agents/provider.py): `packages/agents/provider.py`
- [Report store](https://github.com/mkdirer/ai-sre-platform/blob/main/packages/persistence/investigation_store.py): `packages/persistence/investigation_store.py`

### Knowledge and evaluation

- [Knowledge retrieval](https://github.com/mkdirer/ai-sre-platform/blob/main/packages/rag/service.py): `packages/rag/service.py`
- [Embedding provider](https://github.com/mkdirer/ai-sre-platform/blob/main/packages/rag/embeddings.py): `packages/rag/embeddings.py`
- [Knowledge store](https://github.com/mkdirer/ai-sre-platform/blob/main/packages/persistence/knowledge_store.py): `packages/persistence/knowledge_store.py`
- [Investigation evals](https://github.com/mkdirer/ai-sre-platform/blob/main/packages/evals/scenario.py): `packages/evals/scenario.py`

### Approval and recovery

- [Approval store](https://github.com/mkdirer/ai-sre-platform/blob/main/packages/persistence/approval_store.py): `packages/persistence/approval_store.py`
- [Remediation service](https://github.com/mkdirer/ai-sre-platform/blob/main/packages/remediation/service.py): `packages/remediation/service.py`
- [Execution store](https://github.com/mkdirer/ai-sre-platform/blob/main/packages/persistence/remediation_store.py): `packages/persistence/remediation_store.py`
- [Rollback adapter](https://github.com/mkdirer/ai-sre-platform/blob/main/packages/remediation/adapter.py): `packages/remediation/adapter.py`

### Other components

- **Alertmanager**
- **Reviewer**

## Connections

- Alertmanager → Incident API: sends alerts (evidence: `README.md`)
- Incident API → Incident store: persists incidents (evidence: `README.md`)
- Incident API → Task queue: queues jobs (evidence: `README.md`)
- Task queue → Investigator worker: dispatches jobs (evidence: `README.md`)
- Reviewer → Review UI: reviews incidents (evidence: `README.md`)
- Review UI → API client: requests data
- API client → Incident API: calls API (evidence: `README.md`)
- Investigator worker → Evidence collection: collects evidence (evidence: `apps/investigator_worker/celery_app.py`)
- Evidence collection → Metrics adapter: queries metrics (evidence: `packages/incidents/evidence_collection.py`)
- Evidence collection → Logs adapter: queries logs (evidence: `packages/incidents/evidence_collection.py`)
- Evidence collection → Traces adapter: queries traces (evidence: `packages/incidents/evidence_collection.py`)
- Evidence collection → Deployment evidence: queries deployments (evidence: `packages/incidents/evidence_collection.py`)
- Investigator worker → Investigation workflow: runs investigation (evidence: `apps/investigator_worker/celery_app.py`)
- Investigation workflow → Model provider: requests analysis (evidence: `packages/agents/workflow.py`)
- Investigation workflow → Evidence store: reads evidence (evidence: `packages/agents/workflow.py`)
- Investigation workflow → Report store: stores reports
- Investigation workflow → Knowledge retrieval: retrieves context (evidence: `packages/agents/workflow.py`)
- Knowledge retrieval → Embedding provider: embeds text (evidence: `packages/rag/service.py`)
- Knowledge retrieval → Knowledge store: searches knowledge (evidence: `packages/rag/service.py`)
- Investigation evals → Investigation workflow: evaluates workflow (evidence: `packages/evals/fixtures.py`)
- Incident API → Approval store: records decisions
- Incident API → Remediation service: requests approved action (evidence: `README.md`)
- Remediation service → Execution store: claims executions (evidence: `packages/remediation/service.py`)
- Remediation service → Rollback adapter: runs rollback (evidence: `packages/remediation/service.py`)
- Remediation service → Metrics adapter: checks recovery (evidence: `packages/remediation/service.py`)