# add-it-ya/drdoom architecture

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

- Interactive diagram: https://gitdiagram.com/add-it-ya/drdoom
- Repository: https://github.com/add-it-ya/drdoom

## Overview

DrDoom is an autonomous incident-response service: submitted metric windows are scored, classified, investigated against operational documentation, and turned into a risk-rated remediation held at a human approval gate before execution; reporting and audit preserve the outcome. The API starts and resumes the investigation graph, which owns stage ordering and routing. The repository also includes telemetry preparation and detector/classifier training, plus retrieval evaluation. Relationships beyond the excerpts are included only where documented in the README or named by the SOURCE INDEX; unsampled internals are not assumed.

Main entry points: [`src/drdoom/agents/graph.py`](https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/agents/graph.py) (Investigation graph), [`src/drdoom/agents/diagnosis.py`](https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/agents/diagnosis.py) (Diagnosis agent), [`src/drdoom/agents/remediation.py`](https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/agents/remediation.py) (Remediation agent), [`src/drdoom/api/factory.py`](https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/api/factory.py) (Service assembly)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Telemetry and features"]
  node_synthetic["Synthetic telemetry<br/>[synthetic.py]"]
  node_smd["SMD telemetry<br/>[smd.py]"]
  node_schema["Metric schema<br/>[schema.py]"]
  node_windows["Windowing<br/>[windows.py]"]
end

subgraph group_models["Detection and classification"]
  node_detectors["Anomaly detectors"]
  node_classifier["Cause classifier<br/>[features.py]"]
end

subgraph group_investigation["Investigation workflow"]
  node_graph["Investigation graph<br/>[graph.py]"]
  node_triage["Triage and classification<br/>[triage.py]"]
  node_diagnosis["Diagnosis agent<br/>[diagnosis.py]"]
  node_remediation["Remediation agent<br/>[remediation.py]"]
  node_risk["Risk assessor<br/>[risk.py]"]
  node_reporting["Postmortem writer<br/>[reporting.py]"]
end

subgraph group_knowledge["Documentation and models"]
  node_corpus["Operations corpus<br/>[corpus.py]"]
  node_ingest_docs["Document chunking<br/>[ingest.py]"]
  node_retrieval["Hybrid retrieval<br/>[index.py]"]
  node_rerank["Passage reranker<br/>[rerank.py]"]
  node_llm["LLM providers<br/>[factory.py]"]
end

subgraph group_service["Service and governance"]
  node_metric_api["Window API<br/>[main.py]"]
  node_assembly["Service assembly<br/>[factory.py]"]
  node_executor["Approval and execution<br/>[executor.py]"]
  node_audit[("Append-only audit<br/>[audit.py]")]
  node_observability["Observability<br/>[observability.py]"]
end

node_operator(("On-call engineer"))

node_operator -->|"submits windows"| node_metric_api
node_metric_api -->|"starts or resumes"| node_graph
node_assembly -->|"generates traffic"| node_synthetic
node_assembly -->|"builds detector"| node_detectors
node_assembly -->|"assembles service"| node_graph
node_smd -->|"loads as"| node_schema
node_synthetic -->|"generates as"| node_schema
node_windows -->|"windows series"| node_schema
node_detectors -->|"scores windows"| node_windows
node_triage -->|"checks anomaly"| node_detectors
node_triage -->|"classifies cause"| node_classifier
node_graph -->|"runs triage"| node_triage
node_graph -->|"runs diagnosis"| node_diagnosis
node_graph -->|"requests plan"| node_remediation
node_graph -->|"assesses risk"| node_risk
node_graph -->|"gates execution"| node_executor
node_graph -->|"writes report"| node_reporting
node_corpus -->|"provides documents"| node_ingest_docs
node_diagnosis -->|"searches evidence"| node_retrieval
node_diagnosis -->|"reranks shortlist"| node_rerank
node_diagnosis -->|"generates explanation"| node_llm
node_remediation -->|"searches guidance"| node_retrieval
node_remediation -->|"reranks shortlist"| node_rerank
node_remediation -->|"proposes fix"| node_llm
node_risk -->|"assesses plan"| node_llm
node_executor -->|"records decision"| node_audit
node_metric_api -->|"reports health"| node_observability
node_operator -->|"approves plan"| node_executor

click node_metric_api "https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/api/main.py"
click node_assembly "https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/api/factory.py"
click node_graph "https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/agents/graph.py"
click node_synthetic "https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/data/synthetic.py"
click node_smd "https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/data/smd.py"
click node_schema "https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/data/schema.py"
click node_windows "https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/data/windows.py"
click node_detectors "https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/detect/conv_autoencoder.py"
click node_triage "https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/agents/triage.py"
click node_classifier "https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/classify/features.py"
click node_diagnosis "https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/agents/diagnosis.py"
click node_remediation "https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/agents/remediation.py"
click node_risk "https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/agents/risk.py"
click node_reporting "https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/agents/reporting.py"
click node_corpus "https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/rag/corpus.py"
click node_ingest_docs "https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/rag/ingest.py"
click node_retrieval "https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/rag/index.py"
click node_rerank "https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/rag/rerank.py"
click node_llm "https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/llm/factory.py"
click node_executor "https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/executor.py"
click node_audit "https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/audit.py"
click node_observability "https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/observability.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_synthetic,node_smd,node_schema,node_windows toneBlue
class node_detectors,node_classifier toneAmber
class node_graph,node_triage,node_diagnosis,node_remediation,node_risk,node_reporting toneMint
class node_corpus,node_ingest_docs,node_retrieval,node_rerank,node_llm toneRose
class node_metric_api,node_assembly,node_executor,node_audit,node_observability,node_operator toneIndigo
```

## Components

### Telemetry and features

- [Synthetic telemetry](https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/data/synthetic.py): `src/drdoom/data/synthetic.py`
- [SMD telemetry](https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/data/smd.py): `src/drdoom/data/smd.py`
- [Metric schema](https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/data/schema.py): `src/drdoom/data/schema.py`
- [Windowing](https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/data/windows.py): `src/drdoom/data/windows.py`

### Detection and classification

- [Anomaly detectors](https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/detect/conv_autoencoder.py): `src/drdoom/detect/conv_autoencoder.py`
- [Cause classifier](https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/classify/features.py): `src/drdoom/classify/features.py`

### Investigation workflow

- [Investigation graph](https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/agents/graph.py): `src/drdoom/agents/graph.py`
- [Triage and classification](https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/agents/triage.py): `src/drdoom/agents/triage.py`
- [Diagnosis agent](https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/agents/diagnosis.py): `src/drdoom/agents/diagnosis.py`
- [Remediation agent](https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/agents/remediation.py): `src/drdoom/agents/remediation.py`
- [Risk assessor](https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/agents/risk.py): `src/drdoom/agents/risk.py`
- [Postmortem writer](https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/agents/reporting.py): `src/drdoom/agents/reporting.py`

### Documentation and models

- [Operations corpus](https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/rag/corpus.py): `src/drdoom/rag/corpus.py`
- [Document chunking](https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/rag/ingest.py): `src/drdoom/rag/ingest.py`
- [Hybrid retrieval](https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/rag/index.py): `src/drdoom/rag/index.py`
- [Passage reranker](https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/rag/rerank.py): `src/drdoom/rag/rerank.py`
- [LLM providers](https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/llm/factory.py): `src/drdoom/llm/factory.py`

### Service and governance

- [Window API](https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/api/main.py): `src/drdoom/api/main.py`
- [Service assembly](https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/api/factory.py): `src/drdoom/api/factory.py`
- [Approval and execution](https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/executor.py): `src/drdoom/executor.py`
- [Append-only audit](https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/audit.py): `src/drdoom/audit.py`
- [Observability](https://github.com/add-it-ya/drdoom/blob/main/src/drdoom/observability.py): `src/drdoom/observability.py`

### Other components

- **On-call engineer**

## Connections

- On-call engineer → Window API: submits windows (evidence: `README.md`)
- Window API → Investigation graph: starts or resumes (evidence: `src/drdoom/api/main.py`)
- Service assembly → Synthetic telemetry: generates traffic (evidence: `src/drdoom/api/factory.py`)
- Service assembly → Anomaly detectors: builds detector (evidence: `src/drdoom/api/factory.py`)
- Service assembly → Investigation graph: assembles service (evidence: `src/drdoom/api/factory.py`)
- SMD telemetry → Metric schema: loads as (evidence: `src/drdoom/data/smd.py`)
- Synthetic telemetry → Metric schema: generates as (evidence: `src/drdoom/data/synthetic.py`)
- Windowing → Metric schema: windows series (evidence: `src/drdoom/data/windows.py`)
- Anomaly detectors → Windowing: scores windows (evidence: `README.md`)
- Triage and classification → Anomaly detectors: checks anomaly (evidence: `src/drdoom/agents/triage.py`)
- Triage and classification → Cause classifier: classifies cause (evidence: `src/drdoom/agents/triage.py`)
- Investigation graph → Triage and classification: runs triage (evidence: `src/drdoom/agents/graph.py`)
- Investigation graph → Diagnosis agent: runs diagnosis (evidence: `src/drdoom/agents/graph.py`)
- Investigation graph → Remediation agent: requests plan (evidence: `src/drdoom/agents/graph.py`)
- Investigation graph → Risk assessor: assesses risk (evidence: `src/drdoom/agents/graph.py`)
- Investigation graph → Approval and execution: gates execution (evidence: `src/drdoom/agents/graph.py`)
- Investigation graph → Postmortem writer: writes report (evidence: `src/drdoom/agents/graph.py`)
- Operations corpus → Document chunking: provides documents (evidence: `src/drdoom/rag/ingest.py`)
- Diagnosis agent → Hybrid retrieval: searches evidence (evidence: `src/drdoom/agents/diagnosis.py`)
- Diagnosis agent → Passage reranker: reranks shortlist (evidence: `src/drdoom/agents/diagnosis.py`)
- Diagnosis agent → LLM providers: generates explanation (evidence: `src/drdoom/agents/diagnosis.py`)
- Remediation agent → Hybrid retrieval: searches guidance (evidence: `src/drdoom/agents/remediation.py`)
- Remediation agent → Passage reranker: reranks shortlist (evidence: `src/drdoom/agents/remediation.py`)
- Remediation agent → LLM providers: proposes fix (evidence: `src/drdoom/agents/remediation.py`)
- Risk assessor → LLM providers: assesses plan (evidence: `src/drdoom/agents/risk.py`)
- Approval and execution → Append-only audit: records decision (evidence: `README.md`)
- Window API → Observability: reports health (evidence: `src/drdoom/api/main.py`)
- On-call engineer → Approval and execution: approves plan (evidence: `README.md`)