# irajput215/incident-response-agent architecture

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

- Interactive diagram: https://gitdiagram.com/irajput215/incident-response-agent
- Repository: https://github.com/irajput215/incident-response-agent

## Overview

This is an incident-response agent for failed data pipelines. An orchestrator or on-call user submits an alert; the workflow triages it, gathers evidence with typed log, metadata, and read-only warehouse tools, assesses root cause, plans remediation, pauses for human approval when changes are required, then executes the approved action and records a report. PostgreSQL-backed state supports persistence and resumption; evaluation and observability are important supporting capabilities. The graph follows documented workflow relationships; unsampled implementation details are not inferred.

Main entry points: [`app/agents/nodes.py`](https://github.com/irajput215/incident-response-agent/blob/main/app/agents/nodes.py) (Triage and investigation), [`app/tools/registry.py`](https://github.com/irajput215/incident-response-agent/blob/main/app/tools/registry.py) (Typed tool registry), [`app/agents/agent.py`](https://github.com/irajput215/incident-response-agent/blob/main/app/agents/agent.py) (Agent assembly), [`app/api/routes.py`](https://github.com/irajput215/incident-response-agent/blob/main/app/api/routes.py) (Incident API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Incident entry"]
  node_api["Incident API<br/>[routes.py]"]
end

subgraph group_workflow["Investigation workflow"]
  node_agent["Agent assembly<br/>[agent.py]"]
  node_graph["Workflow graph<br/>[graph.py]"]
  node_stages["Triage and investigation<br/>[nodes.py]"]
  node_domain["Incident domain models<br/>[schemas.py]"]
  node_llm["LLM clients<br/>[__init__.py]"]
end

subgraph group_evidence["Evidence and tools"]
  node_registry["Typed tool registry<br/>[registry.py]"]
  node_logtools["Log investigation<br/>[logs.py]"]
  node_pipetools["Pipeline metadata<br/>[pipeline.py]"]
  node_warehouse["Warehouse queries<br/>[database.py]"]
  node_sqlguard["Read-only SQL guard<br/>[sql_guard.py]"]
  node_estate["Pipeline estate<br/>[estate.py]"]
end

subgraph group_state["State and reporting"]
  node_repository["Incident repository<br/>[repository.py]"]
  node_platformdb[("Platform PostgreSQL<br/>[schema.py]")]
  node_checkpoint["Graph checkpointing<br/>[platform.py]"]
end

subgraph group_support["Operations and evaluation"]
  node_observability["Metrics and logging<br/>[observability.py]"]
  node_tracing["LangSmith tracing<br/>[tracing.py]"]
  node_evaluation["Agent evaluation<br/>[harness.py]"]
end

node_orchestrator(("Alert source"))
node_human(("On-call reviewer"))

node_orchestrator -->|"submits alert"| node_api
node_human -->|"approves or rejects"| node_api
node_api -->|"starts investigation"| node_agent
node_agent -->|"builds workflow"| node_graph
node_graph -->|"dispatches stages"| node_stages
node_stages -->|"requests analysis"| node_llm
node_stages -->|"invokes tools"| node_registry
node_registry -->|"registers tools"| node_logtools
node_registry -->|"registers tools"| node_pipetools
node_registry -->|"registers tools"| node_warehouse
node_warehouse -->|"checks queries"| node_sqlguard
node_logtools -.->|"reads pipeline estate"| node_estate
node_pipetools -.->|"reads metadata"| node_estate
node_warehouse -.->|"uses estate context"| node_estate
node_stages -->|"records evidence"| node_repository
node_repository -.->|"persists incident data"| node_platformdb
node_agent -->|"configures graph state"| node_checkpoint
node_graph -->|"suspends for approval"| node_checkpoint
node_stages -->|"requests approval"| node_human
node_stages -->|"returns report"| node_api
node_stages -.->|"records run metrics"| node_observability
node_stages -.->|"emits traces"| node_tracing
node_evaluation -->|"evaluates outcomes"| node_agent

click node_api "https://github.com/irajput215/incident-response-agent/blob/main/app/api/routes.py"
click node_agent "https://github.com/irajput215/incident-response-agent/blob/main/app/agents/agent.py"
click node_graph "https://github.com/irajput215/incident-response-agent/blob/main/app/agents/graph.py"
click node_stages "https://github.com/irajput215/incident-response-agent/blob/main/app/agents/nodes.py"
click node_domain "https://github.com/irajput215/incident-response-agent/blob/main/app/schemas.py"
click node_llm "https://github.com/irajput215/incident-response-agent/blob/main/app/llm/__init__.py"
click node_registry "https://github.com/irajput215/incident-response-agent/blob/main/app/tools/registry.py"
click node_logtools "https://github.com/irajput215/incident-response-agent/blob/main/app/tools/logs.py"
click node_pipetools "https://github.com/irajput215/incident-response-agent/blob/main/app/tools/pipeline.py"
click node_warehouse "https://github.com/irajput215/incident-response-agent/blob/main/app/tools/database.py"
click node_sqlguard "https://github.com/irajput215/incident-response-agent/blob/main/app/tools/sql_guard.py"
click node_estate "https://github.com/irajput215/incident-response-agent/blob/main/app/estate.py"
click node_repository "https://github.com/irajput215/incident-response-agent/blob/main/app/db/repository.py"
click node_platformdb "https://github.com/irajput215/incident-response-agent/blob/main/app/db/schema.py"
click node_checkpoint "https://github.com/irajput215/incident-response-agent/blob/main/app/platform.py"
click node_observability "https://github.com/irajput215/incident-response-agent/blob/main/app/observability.py"
click node_tracing "https://github.com/irajput215/incident-response-agent/blob/main/app/tracing.py"
click node_evaluation "https://github.com/irajput215/incident-response-agent/blob/main/app/evaluation/harness.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_human toneBlue
class node_agent,node_graph,node_stages,node_domain,node_llm toneAmber
class node_registry,node_logtools,node_pipetools,node_warehouse,node_sqlguard,node_estate toneMint
class node_repository,node_platformdb,node_checkpoint toneRose
class node_observability,node_tracing,node_evaluation,node_orchestrator toneIndigo
```

## Components

### Incident entry

- [Incident API](https://github.com/irajput215/incident-response-agent/blob/main/app/api/routes.py): `app/api/routes.py`

### Investigation workflow

- [Agent assembly](https://github.com/irajput215/incident-response-agent/blob/main/app/agents/agent.py): `app/agents/agent.py`
- [Workflow graph](https://github.com/irajput215/incident-response-agent/blob/main/app/agents/graph.py): `app/agents/graph.py`
- [Triage and investigation](https://github.com/irajput215/incident-response-agent/blob/main/app/agents/nodes.py): `app/agents/nodes.py`
- [Incident domain models](https://github.com/irajput215/incident-response-agent/blob/main/app/schemas.py): `app/schemas.py`
- [LLM clients](https://github.com/irajput215/incident-response-agent/blob/main/app/llm/__init__.py): `app/llm/__init__.py`

### Evidence and tools

- [Typed tool registry](https://github.com/irajput215/incident-response-agent/blob/main/app/tools/registry.py): `app/tools/registry.py`
- [Log investigation](https://github.com/irajput215/incident-response-agent/blob/main/app/tools/logs.py): `app/tools/logs.py`
- [Pipeline metadata](https://github.com/irajput215/incident-response-agent/blob/main/app/tools/pipeline.py): `app/tools/pipeline.py`
- [Warehouse queries](https://github.com/irajput215/incident-response-agent/blob/main/app/tools/database.py): `app/tools/database.py`
- [Read-only SQL guard](https://github.com/irajput215/incident-response-agent/blob/main/app/tools/sql_guard.py): `app/tools/sql_guard.py`
- [Pipeline estate](https://github.com/irajput215/incident-response-agent/blob/main/app/estate.py): `app/estate.py`

### State and reporting

- [Incident repository](https://github.com/irajput215/incident-response-agent/blob/main/app/db/repository.py): `app/db/repository.py`
- [Platform PostgreSQL](https://github.com/irajput215/incident-response-agent/blob/main/app/db/schema.py): `app/db/schema.py`
- [Graph checkpointing](https://github.com/irajput215/incident-response-agent/blob/main/app/platform.py): `app/platform.py`

### Operations and evaluation

- [Metrics and logging](https://github.com/irajput215/incident-response-agent/blob/main/app/observability.py): `app/observability.py`
- [LangSmith tracing](https://github.com/irajput215/incident-response-agent/blob/main/app/tracing.py): `app/tracing.py`
- [Agent evaluation](https://github.com/irajput215/incident-response-agent/blob/main/app/evaluation/harness.py): `app/evaluation/harness.py`

### Other components

- **Alert source**
- **On-call reviewer**

## Connections

- Alert source → Incident API: submits alert (evidence: `README.md`)
- On-call reviewer → Incident API: approves or rejects (evidence: `README.md`)
- Incident API → Agent assembly: starts investigation (evidence: `README.md`)
- Agent assembly → Workflow graph: builds workflow (evidence: `app/agents/agent.py`)
- Workflow graph → Triage and investigation: dispatches stages (evidence: `app/agents/graph.py`)
- Triage and investigation → LLM clients: requests analysis (evidence: `app/agents/nodes.py`)
- Triage and investigation → Typed tool registry: invokes tools (evidence: `app/agents/nodes.py`)
- Typed tool registry → Log investigation: registers tools (evidence: `app/tools/__init__.py`)
- Typed tool registry → Pipeline metadata: registers tools (evidence: `app/tools/__init__.py`)
- Typed tool registry → Warehouse queries: registers tools (evidence: `app/tools/__init__.py`)
- Warehouse queries → Read-only SQL guard: checks queries (evidence: `app/tools/database.py`)
- Log investigation → Pipeline estate: reads pipeline estate
- Pipeline metadata → Pipeline estate: reads metadata
- Warehouse queries → Pipeline estate: uses estate context (evidence: `app/tools/database.py`)
- Triage and investigation → Incident repository: records evidence (evidence: `app/agents/nodes.py`)
- Incident repository → Platform PostgreSQL: persists incident data
- Agent assembly → Graph checkpointing: configures graph state (evidence: `app/platform.py`)
- Workflow graph → Graph checkpointing: suspends for approval (evidence: `README.md`)
- Triage and investigation → On-call reviewer: requests approval (evidence: `README.md`)
- Triage and investigation → Incident API: returns report (evidence: `README.md`)
- Triage and investigation → Metrics and logging: records run metrics (evidence: `app/agents/nodes.py`)
- Triage and investigation → LangSmith tracing: emits traces (evidence: `app/agents/nodes.py`)
- Agent evaluation → Agent assembly: evaluates outcomes (evidence: `app/evaluation/harness.py`)
