# harshadpatil108/mlsd-mini-project architecture

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

- Interactive diagram: https://gitdiagram.com/harshadpatil108/mlsd-mini-project
- Repository: https://github.com/harshadpatil108/mlsd-mini-project

## Overview

IncidentOps accepts PostgreSQL alerts, validates and queues them, then asynchronously produces advisory cause classifications, verified citations, first-response steps, and a human route. Its agent graph performs triage, multi-hop investigation, and citation verification; RAG indexes PostgreSQL documentation and runbooks for hybrid retrieval. The README documents the service boundaries and guardrail behavior; source excerpts and the SOURCE INDEX support the implementation links shown. Some guardrail and deployment wiring is documented but not shown in source excerpts, so those links are marked dashed.

Main entry points: [`src/api/main.py`](https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/api/main.py) (Run API), [`src/agent/graph.py`](https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/agent/graph.py) (Agent Workflow), [`src/rag/ingestion.py`](https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/rag/ingestion.py) (Corpus Ingestion), [`src/worker/main.py`](https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/worker/main.py) (Background Worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Alert Intake"]
  node_frontend["Streamlit UI<br/>[app.py]"]
  node_api["Run API<br/>[main.py]"]
  node_contracts["Alert Contracts<br/>[schemas.py]"]
  node_quarantine[("Quarantine Store<br/>[quarantine.py]")]
end

subgraph group_reasoning["Incident Reasoning"]
  node_graph["Agent Workflow<br/>[graph.py]"]
  node_state["Agent State<br/>[state.py]"]
  node_triage["Triage Agent<br/>[triage.py]"]
  node_investigator["Investigator Agent<br/>[investigator.py]"]
  node_verifier["Citation Verifier<br/>[verifier.py]"]
end

subgraph group_knowledge["Knowledge Retrieval"]
  node_tools["Retrieval Tools<br/>[tools.py]"]
  node_retriever["Hybrid Retriever<br/>[retriever.py]"]
  node_bm25[("BM25 Index<br/>[bm25.py]")]
  node_chroma[("Chroma Vector Store<br/>[store.py]")]
  node_ingestion["Corpus Ingestion<br/>[ingestion.py]"]
  node_parsers["Document Parsers<br/>[parsers.py]"]
  node_chunker["Hierarchical Chunker<br/>[chunker.py]"]
end

subgraph group_operations["Runtime Services"]
  node_queue["Task Queue<br/>[queue.py]"]
  node_runstore[("Run Status Store<br/>[store.py]")]
  node_worker["Background Worker<br/>[main.py]"]
  node_gateway["LLM Gateway<br/>[client.py]"]
end

subgraph group_safety["Safety Controls"]
  node_injection["Injection Defense<br/>[injection.py]"]
  node_toxicity["Toxicity Scan<br/>[toxicity.py]"]
  node_outputfilter["Output Authorization<br/>[output.py]"]
end

node_oncall(("On-call Engineer"))
node_prometheus(("Prometheus Client"))
node_browser(("Browser User"))
node_redis["Redis Broker"]
node_llm(("LLM Provider"))

node_oncall -->|"submits alert"| node_frontend
node_browser -->|"uses UI"| node_frontend
node_prometheus -->|"submits alert"| node_api
node_frontend -->|"sends HTTP"| node_api
node_api -->|"validates with"| node_contracts
node_api -->|"stores rejects"| node_quarantine
node_api -->|"records run"| node_runstore
node_api -->|"enqueues run"| node_queue
node_api -.->|"screens note"| node_injection
node_api -.->|"scans input"| node_toxicity
node_queue -->|"pushes tasks"| node_redis
node_redis -->|"delivers run"| node_worker
node_worker -->|"dequeues run"| node_queue
node_worker -->|"updates status"| node_runstore
node_worker -->|"invokes graph"| node_graph
node_graph -->|"runs triage"| node_triage
node_graph -->|"runs investigation"| node_investigator
node_graph -->|"verifies output"| node_verifier
node_graph -->|"updates state"| node_state
node_triage -->|"requests reasoning"| node_gateway
node_investigator -->|"uses search tools"| node_tools
node_investigator -->|"requests synthesis"| node_gateway
node_verifier -->|"requests verification"| node_gateway
node_tools -->|"searches corpus"| node_retriever
node_retriever -->|"queries dense"| node_chroma
node_retriever -->|"queries sparse"| node_bm25
node_ingestion -->|"parses documents"| node_parsers
node_ingestion -->|"chunks sections"| node_chunker
node_ingestion -->|"indexes chunks"| node_chroma
node_ingestion -->|"builds index"| node_bm25
node_gateway -->|"sends completions"| node_llm
node_graph -.->|"filters result"| node_outputfilter
node_verifier -.->|"returns verified result"| node_runstore

click node_frontend "https://github.com/harshadpatil108/mlsd-mini-project/blob/main/frontend/app.py"
click node_api "https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/api/main.py"
click node_contracts "https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/api/schemas.py"
click node_quarantine "https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/api/quarantine.py"
click node_queue "https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/worker/queue.py"
click node_runstore "https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/worker/store.py"
click node_worker "https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/worker/main.py"
click node_graph "https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/agent/graph.py"
click node_state "https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/agent/state.py"
click node_triage "https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/agent/triage.py"
click node_investigator "https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/agent/investigator.py"
click node_verifier "https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/agent/verifier.py"
click node_tools "https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/agent/tools.py"
click node_retriever "https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/rag/retriever.py"
click node_bm25 "https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/rag/bm25.py"
click node_chroma "https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/rag/store.py"
click node_ingestion "https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/rag/ingestion.py"
click node_parsers "https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/rag/parsers.py"
click node_chunker "https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/rag/chunker.py"
click node_gateway "https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/gateway/client.py"
click node_injection "https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/guardrails/injection.py"
click node_toxicity "https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/guardrails/toxicity.py"
click node_outputfilter "https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/guardrails/output.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_api,node_contracts,node_quarantine,node_prometheus,node_browser toneBlue
class node_graph,node_state,node_triage,node_investigator,node_verifier,node_redis toneAmber
class node_tools,node_retriever,node_bm25,node_chroma,node_ingestion,node_parsers,node_chunker toneMint
class node_queue,node_runstore,node_worker,node_gateway toneRose
class node_injection,node_toxicity,node_outputfilter,node_oncall,node_llm toneIndigo
```

## Components

### Alert Intake

- [Streamlit UI](https://github.com/harshadpatil108/mlsd-mini-project/blob/main/frontend/app.py): `frontend/app.py`
- [Run API](https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/api/main.py): `src/api/main.py`
- [Alert Contracts](https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/api/schemas.py): `src/api/schemas.py`
- [Quarantine Store](https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/api/quarantine.py): `src/api/quarantine.py`

### Incident Reasoning

- [Agent Workflow](https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/agent/graph.py): `src/agent/graph.py`
- [Agent State](https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/agent/state.py): `src/agent/state.py`
- [Triage Agent](https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/agent/triage.py): `src/agent/triage.py`
- [Investigator Agent](https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/agent/investigator.py): `src/agent/investigator.py`
- [Citation Verifier](https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/agent/verifier.py): `src/agent/verifier.py`

### Knowledge Retrieval

- [Retrieval Tools](https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/agent/tools.py): `src/agent/tools.py`
- [Hybrid Retriever](https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/rag/retriever.py): `src/rag/retriever.py`
- [BM25 Index](https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/rag/bm25.py): `src/rag/bm25.py`
- [Chroma Vector Store](https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/rag/store.py): `src/rag/store.py`
- [Corpus Ingestion](https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/rag/ingestion.py): `src/rag/ingestion.py`
- [Document Parsers](https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/rag/parsers.py): `src/rag/parsers.py`
- [Hierarchical Chunker](https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/rag/chunker.py): `src/rag/chunker.py`

### Runtime Services

- [Task Queue](https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/worker/queue.py): `src/worker/queue.py`
- [Run Status Store](https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/worker/store.py): `src/worker/store.py`
- [Background Worker](https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/worker/main.py): `src/worker/main.py`
- [LLM Gateway](https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/gateway/client.py): `src/gateway/client.py`

### Safety Controls

- [Injection Defense](https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/guardrails/injection.py): `src/guardrails/injection.py`
- [Toxicity Scan](https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/guardrails/toxicity.py): `src/guardrails/toxicity.py`
- [Output Authorization](https://github.com/harshadpatil108/mlsd-mini-project/blob/main/src/guardrails/output.py): `src/guardrails/output.py`

### Other components

- **On-call Engineer**
- **Prometheus Client**
- **Browser User**
- **Redis Broker**
- **LLM Provider**

## Connections

- On-call Engineer → Streamlit UI: submits alert
- Browser User → Streamlit UI: uses UI
- Prometheus Client → Run API: submits alert
- Streamlit UI → Run API: sends HTTP
- Run API → Alert Contracts: validates with (evidence: `src/api/main.py`)
- Run API → Quarantine Store: stores rejects (evidence: `src/api/main.py`)
- Run API → Run Status Store: records run (evidence: `src/api/main.py`)
- Run API → Task Queue: enqueues run (evidence: `src/api/main.py`)
- Run API → Injection Defense: screens note
- Run API → Toxicity Scan: scans input
- Task Queue → Redis Broker: pushes tasks
- Redis Broker → Background Worker: delivers run
- Background Worker → Task Queue: dequeues run (evidence: `src/worker/main.py`)
- Background Worker → Run Status Store: updates status (evidence: `src/worker/main.py`)
- Background Worker → Agent Workflow: invokes graph (evidence: `src/worker/main.py`)
- Agent Workflow → Triage Agent: runs triage (evidence: `src/agent/graph.py`)
- Agent Workflow → Investigator Agent: runs investigation (evidence: `src/agent/graph.py`)
- Agent Workflow → Citation Verifier: verifies output (evidence: `src/agent/graph.py`)
- Agent Workflow → Agent State: updates state (evidence: `src/agent/graph.py`)
- Triage Agent → LLM Gateway: requests reasoning (evidence: `src/agent/triage.py`)
- Investigator Agent → Retrieval Tools: uses search tools (evidence: `src/agent/investigator.py`)
- Investigator Agent → LLM Gateway: requests synthesis (evidence: `src/agent/investigator.py`)
- Citation Verifier → LLM Gateway: requests verification (evidence: `src/agent/verifier.py`)
- Retrieval Tools → Hybrid Retriever: searches corpus (evidence: `src/agent/tools.py`)
- Hybrid Retriever → Chroma Vector Store: queries dense (evidence: `src/rag/retriever.py`)
- Hybrid Retriever → BM25 Index: queries sparse (evidence: `src/rag/retriever.py`)
- Corpus Ingestion → Document Parsers: parses documents (evidence: `src/rag/ingestion.py`)
- Corpus Ingestion → Hierarchical Chunker: chunks sections (evidence: `src/rag/ingestion.py`)
- Corpus Ingestion → Chroma Vector Store: indexes chunks (evidence: `src/rag/ingestion.py`)
- Corpus Ingestion → BM25 Index: builds index (evidence: `src/rag/ingestion.py`)
- LLM Gateway → LLM Provider: sends completions
- Agent Workflow → Output Authorization: filters result
- Citation Verifier → Run Status Store: returns verified result
