# karthik14344/ai-incident-doctor architecture

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

- Interactive diagram: https://gitdiagram.com/karthik14344/ai-incident-doctor
- Repository: https://github.com/karthik14344/ai-incident-doctor

## Overview

AI Incident Doctor is a fault-injection and diagnosis project with two deliberately separate systems: KnowledgeAI, the patient application, and the Doctor, which diagnoses reported or alerted incidents. The user-facing path runs from the React interface through the gateway to document ingestion, retrieval, and model-backed answers. The operational path runs from monitoring alerts or user tickets through evidence collection, suspect-code retrieval, diagnosis, fix verification, and reporting. The README documents further capabilities whose internal wiring was not sampled; those relationships are cited to the README. Source excerpts and the index support the remaining relationships.

Main entry points: [`doctor/app/reasoner.py`](https://github.com/karthik14344/ai-incident-doctor/blob/main/doctor/app/reasoner.py) (Root-cause reasoning), [`doctor/app/main.py`](https://github.com/karthik14344/ai-incident-doctor/blob/main/doctor/app/main.py) (Incident intake), [`patient/api_gateway/app/main.py`](https://github.com/karthik14344/ai-incident-doctor/blob/main/patient/api_gateway/app/main.py) (API gateway), [`patient/ingestion_service/app/main.py`](https://github.com/karthik14344/ai-incident-doctor/blob/main/patient/ingestion_service/app/main.py) (Document ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_patient_ui["Patient interface"]
  node_frontend["React interface<br/>[App.jsx]"]
end

subgraph group_patient_services["KnowledgeAI services"]
  node_gateway["API gateway<br/>[main.py]"]
  node_session_db[("Chat and document records<br/>[db.py]")]
  node_ingestion["Document ingestion<br/>[main.py]"]
  node_chunking["Chunking and embeddings<br/>[chunker.py]"]
  node_vector_store[("Vector store<br/>[vector_store.py]")]
  node_retrieval["Context retrieval<br/>[main.py]"]
  node_llm["Answer generation<br/>[main.py]"]
end

subgraph group_doctor["Incident doctor"]
  node_doctor_entry["Incident intake<br/>[main.py]"]
  node_collectors["Evidence collection<br/>[collectors.py]"]
  node_evidence["Evidence bundle<br/>[evidence.py]"]
  node_doctor_retrieval["Suspect retrieval<br/>[retrieval.py]"]
  node_indexes[("Search indexes<br/>[indexes.py]")]
  node_reasoner["Root-cause reasoning<br/>[reasoner.py]"]
  node_llm_client["Doctor model client<br/>[llm.py]"]
  node_fixes["Proposed code fix<br/>[fixes.py]"]
  node_verify["Fix verification<br/>[verify.py]"]
  node_report["Incident report<br/>[report.py]"]
end

subgraph group_operations["Operations and evaluation"]
  node_monitoring["Monitoring and alerts<br/>[build_dashboard.py]"]
  node_alert_sink["Alert sink<br/>[sink.py]"]
  node_faults["Fault injection<br/>[run_fault.py]"]
  node_patient_eval["Patient evaluation<br/>[pipeline.py]"]
  node_doctor_eval["Doctor evaluation<br/>[run_eval.py]"]
end

node_user(("User"))
node_ollama["Ollama model service"]
node_reporter(("Ticket reporter"))
node_replay(("Incident replay"))

node_user -->|"uses"| node_frontend
node_frontend -->|"calls API"| node_gateway
node_gateway -->|"reads and writes"| node_session_db
node_gateway -->|"dispatches processing"| node_ingestion
node_ingestion -->|"creates chunks"| node_chunking
node_ingestion -->|"stores vectors"| node_vector_store
node_gateway -->|"requests context"| node_retrieval
node_retrieval -->|"queries vectors"| node_vector_store
node_gateway -->|"requests answer"| node_llm
node_llm -->|"generates tokens"| node_ollama
node_monitoring -->|"sends alert"| node_alert_sink
node_alert_sink -->|"forwards alert"| node_doctor_entry
node_reporter -->|"submits ticket"| node_doctor_entry
node_replay -->|"starts replay"| node_doctor_entry
node_doctor_entry -->|"collects clues"| node_collectors
node_collectors -->|"builds bundle"| node_evidence
node_doctor_entry -->|"diagnoses bundle"| node_reasoner
node_reasoner -->|"retrieves context"| node_doctor_retrieval
node_doctor_retrieval -->|"uses indexes"| node_indexes
node_reasoner -->|"requests reasoning"| node_llm_client
node_reasoner -->|"proposes repair"| node_fixes
node_reasoner -->|"checks fix"| node_verify
node_doctor_entry -->|"writes report"| node_report
node_faults -.->|"disrupts patient"| node_user
node_patient_eval -->|"evaluates pipeline"| node_retrieval
node_doctor_eval -->|"evaluates diagnosis"| node_reasoner

click node_frontend "https://github.com/karthik14344/ai-incident-doctor/blob/main/patient/frontend/src/App.jsx"
click node_gateway "https://github.com/karthik14344/ai-incident-doctor/blob/main/patient/api_gateway/app/main.py"
click node_session_db "https://github.com/karthik14344/ai-incident-doctor/blob/main/patient/api_gateway/app/db.py"
click node_ingestion "https://github.com/karthik14344/ai-incident-doctor/blob/main/patient/ingestion_service/app/main.py"
click node_chunking "https://github.com/karthik14344/ai-incident-doctor/blob/main/patient/ingestion_service/app/chunker.py"
click node_vector_store "https://github.com/karthik14344/ai-incident-doctor/blob/main/patient/ingestion_service/app/vector_store.py"
click node_retrieval "https://github.com/karthik14344/ai-incident-doctor/blob/main/patient/retrieval_service/app/main.py"
click node_llm "https://github.com/karthik14344/ai-incident-doctor/blob/main/patient/llm_service/app/main.py"
click node_monitoring "https://github.com/karthik14344/ai-incident-doctor/blob/main/monitoring/grafana/build_dashboard.py"
click node_alert_sink "https://github.com/karthik14344/ai-incident-doctor/blob/main/alert_sink/sink.py"
click node_doctor_entry "https://github.com/karthik14344/ai-incident-doctor/blob/main/doctor/app/main.py"
click node_collectors "https://github.com/karthik14344/ai-incident-doctor/blob/main/doctor/app/collectors.py"
click node_evidence "https://github.com/karthik14344/ai-incident-doctor/blob/main/doctor/app/evidence.py"
click node_doctor_retrieval "https://github.com/karthik14344/ai-incident-doctor/blob/main/doctor/app/retrieval.py"
click node_indexes "https://github.com/karthik14344/ai-incident-doctor/blob/main/doctor/app/indexes.py"
click node_reasoner "https://github.com/karthik14344/ai-incident-doctor/blob/main/doctor/app/reasoner.py"
click node_llm_client "https://github.com/karthik14344/ai-incident-doctor/blob/main/doctor/app/llm.py"
click node_fixes "https://github.com/karthik14344/ai-incident-doctor/blob/main/doctor/app/fixes.py"
click node_verify "https://github.com/karthik14344/ai-incident-doctor/blob/main/doctor/app/verify.py"
click node_report "https://github.com/karthik14344/ai-incident-doctor/blob/main/doctor/app/report.py"
click node_faults "https://github.com/karthik14344/ai-incident-doctor/blob/main/faults/run_fault.py"
click node_patient_eval "https://github.com/karthik14344/ai-incident-doctor/blob/main/patient/evaluation/pipeline.py"
click node_doctor_eval "https://github.com/karthik14344/ai-incident-doctor/blob/main/doctor/eval/run_eval.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_frontend,node_user toneBlue
class node_gateway,node_session_db,node_ingestion,node_chunking,node_vector_store,node_retrieval,node_llm toneAmber
class node_doctor_entry,node_collectors,node_evidence,node_doctor_retrieval,node_indexes,node_reasoner,node_llm_client,node_fixes,node_verify,node_report toneMint
class node_monitoring,node_alert_sink,node_faults,node_patient_eval,node_doctor_eval toneRose
class node_ollama,node_reporter,node_replay toneIndigo
```

## Components

### Patient interface

- [React interface](https://github.com/karthik14344/ai-incident-doctor/blob/main/patient/frontend/src/App.jsx): `patient/frontend/src/App.jsx`

### KnowledgeAI services

- [API gateway](https://github.com/karthik14344/ai-incident-doctor/blob/main/patient/api_gateway/app/main.py): `patient/api_gateway/app/main.py`
- [Chat and document records](https://github.com/karthik14344/ai-incident-doctor/blob/main/patient/api_gateway/app/db.py): `patient/api_gateway/app/db.py`
- [Document ingestion](https://github.com/karthik14344/ai-incident-doctor/blob/main/patient/ingestion_service/app/main.py): `patient/ingestion_service/app/main.py`
- [Chunking and embeddings](https://github.com/karthik14344/ai-incident-doctor/blob/main/patient/ingestion_service/app/chunker.py): `patient/ingestion_service/app/chunker.py`
- [Vector store](https://github.com/karthik14344/ai-incident-doctor/blob/main/patient/ingestion_service/app/vector_store.py): `patient/ingestion_service/app/vector_store.py`
- [Context retrieval](https://github.com/karthik14344/ai-incident-doctor/blob/main/patient/retrieval_service/app/main.py): `patient/retrieval_service/app/main.py`
- [Answer generation](https://github.com/karthik14344/ai-incident-doctor/blob/main/patient/llm_service/app/main.py): `patient/llm_service/app/main.py`

### Incident doctor

- [Incident intake](https://github.com/karthik14344/ai-incident-doctor/blob/main/doctor/app/main.py): `doctor/app/main.py`
- [Evidence collection](https://github.com/karthik14344/ai-incident-doctor/blob/main/doctor/app/collectors.py): `doctor/app/collectors.py`
- [Evidence bundle](https://github.com/karthik14344/ai-incident-doctor/blob/main/doctor/app/evidence.py): `doctor/app/evidence.py`
- [Suspect retrieval](https://github.com/karthik14344/ai-incident-doctor/blob/main/doctor/app/retrieval.py): `doctor/app/retrieval.py`
- [Search indexes](https://github.com/karthik14344/ai-incident-doctor/blob/main/doctor/app/indexes.py): `doctor/app/indexes.py`
- [Root-cause reasoning](https://github.com/karthik14344/ai-incident-doctor/blob/main/doctor/app/reasoner.py): `doctor/app/reasoner.py`
- [Doctor model client](https://github.com/karthik14344/ai-incident-doctor/blob/main/doctor/app/llm.py): `doctor/app/llm.py`
- [Proposed code fix](https://github.com/karthik14344/ai-incident-doctor/blob/main/doctor/app/fixes.py): `doctor/app/fixes.py`
- [Fix verification](https://github.com/karthik14344/ai-incident-doctor/blob/main/doctor/app/verify.py): `doctor/app/verify.py`
- [Incident report](https://github.com/karthik14344/ai-incident-doctor/blob/main/doctor/app/report.py): `doctor/app/report.py`

### Operations and evaluation

- [Monitoring and alerts](https://github.com/karthik14344/ai-incident-doctor/blob/main/monitoring/grafana/build_dashboard.py): `monitoring/grafana/build_dashboard.py`
- [Alert sink](https://github.com/karthik14344/ai-incident-doctor/blob/main/alert_sink/sink.py): `alert_sink/sink.py`
- [Fault injection](https://github.com/karthik14344/ai-incident-doctor/blob/main/faults/run_fault.py): `faults/run_fault.py`
- [Patient evaluation](https://github.com/karthik14344/ai-incident-doctor/blob/main/patient/evaluation/pipeline.py): `patient/evaluation/pipeline.py`
- [Doctor evaluation](https://github.com/karthik14344/ai-incident-doctor/blob/main/doctor/eval/run_eval.py): `doctor/eval/run_eval.py`

### Other components

- **User**
- **Ollama model service**
- **Ticket reporter**
- **Incident replay**

## Connections

- User → React interface: uses
- React interface → API gateway: calls API
- API gateway → Chat and document records: reads and writes (evidence: `patient/api_gateway/app/main.py`)
- API gateway → Document ingestion: dispatches processing (evidence: `patient/api_gateway/app/main.py`)
- Document ingestion → Chunking and embeddings: creates chunks (evidence: `patient/ingestion_service/app/main.py`)
- Document ingestion → Vector store: stores vectors (evidence: `patient/ingestion_service/app/main.py`)
- API gateway → Context retrieval: requests context
- Context retrieval → Vector store: queries vectors (evidence: `patient/retrieval_service/app/main.py`)
- API gateway → Answer generation: requests answer
- Answer generation → Ollama model service: generates tokens (evidence: `patient/llm_service/app/main.py`)
- Monitoring and alerts → Alert sink: sends alert
- Alert sink → Incident intake: forwards alert
- Ticket reporter → Incident intake: submits ticket
- Incident replay → Incident intake: starts replay
- Incident intake → Evidence collection: collects clues (evidence: `doctor/app/main.py`)
- Evidence collection → Evidence bundle: builds bundle
- Incident intake → Root-cause reasoning: diagnoses bundle (evidence: `doctor/app/main.py`)
- Root-cause reasoning → Suspect retrieval: retrieves context (evidence: `doctor/app/reasoner.py`)
- Suspect retrieval → Search indexes: uses indexes (evidence: `doctor/app/retrieval.py`)
- Root-cause reasoning → Doctor model client: requests reasoning (evidence: `doctor/app/reasoner.py`)
- Root-cause reasoning → Proposed code fix: proposes repair (evidence: `doctor/app/reasoner.py`)
- Root-cause reasoning → Fix verification: checks fix (evidence: `doctor/app/reasoner.py`)
- Incident intake → Incident report: writes report (evidence: `doctor/app/main.py`)
- Fault injection → User: disrupts patient
- Patient evaluation → Context retrieval: evaluates pipeline (evidence: `patient/evaluation/pipeline.py`)
- Doctor evaluation → Root-cause reasoning: evaluates diagnosis (evidence: `doctor/eval/run_eval.py`)
