# zoro-zuro/incident-a architecture

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

- Interactive diagram: https://gitdiagram.com/zoro-zuro/incident-a
- Repository: https://github.com/zoro-zuro/incident-a

## Overview

This is a local-first incident response agent: alerts enter through Redis or the REST API, then an orchestrated workflow investigates, recommends a response, waits for operator approval, and records the outcome for future recall. The workflow includes severity classification, historical-incident recall, evidence gathering, runbook retrieval, decision-making, remediation, verification, and reporting. The API exposes incident and knowledge views to a React dashboard. The README documents the end-to-end flow; sampled source confirms several calls and integrations, but not every workflow transition or API implementation detail.

Main entry points: [`agent/graph.py`](https://github.com/zoro-zuro/incident-a/blob/main/agent/graph.py) (Workflow Orchestrator), [`api/main.py`](https://github.com/zoro-zuro/incident-a/blob/main/api/main.py) (REST API), [`agent/memory.py`](https://github.com/zoro-zuro/incident-a/blob/main/agent/memory.py) (Incident Memory), [`agent/incident_runner.py`](https://github.com/zoro-zuro/incident-a/blob/main/agent/incident_runner.py) (Incident Runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Alert Ingestion"]
  node_redis["Redis Alerts"]
  node_queue_helpers["Queue Helpers<br/>[redis_queue.py]"]
  node_listener["Alert Listener<br/>[listener.py]"]
end

subgraph group_workflow["Incident Workflow"]
  node_runner["Incident Runner<br/>[incident_runner.py]"]
  node_workflow_graph["Workflow Orchestrator<br/>[graph.py]"]
  node_workflow_state["Incident State<br/>[state.py]"]
end

subgraph group_knowledge["Knowledge &amp; Evidence"]
  node_incident_memory[("Incident Memory<br/>[memory.py]")]
  node_runbook_search[("Runbook Retrieval<br/>[rag.py]")]
  node_embeddings["Embedding Helper<br/>[embeddings.py]"]
  node_evidence_tools["Evidence Tools<br/>[tools.py]"]
  node_metrics["Metrics Queries<br/>[metrics.py]"]
  node_simulated_environment[("Simulated Services<br/>[simulated_env.py]")]
end

subgraph group_response["Decision &amp; Response"]
  node_decision_provider["Decision Provider"]
  node_llm["LLM Adapter<br/>[llm.py]"]
  node_reasoner["Reasoning &amp; Retry<br/>[reasoner.py]"]
  node_approval["Human Approval<br/>[approval.py]"]
  node_remediation["Remediation<br/>[remediation.py]"]
end

subgraph group_application["API &amp; Dashboard"]
  node_rest_api["REST API<br/>[main.py]"]
  node_dashboard["React Dashboard<br/>[App.tsx]"]
  node_api_client["API Client<br/>[api.ts]"]
  node_incident_views["Incident Views"]
end

node_alert_source(("Alert Source"))
node_chroma[("ChromaDB")]

node_alert_source -->|"publishes alerts"| node_redis
node_redis -->|"delivers alerts"| node_queue_helpers
node_queue_helpers -->|"dispatches alerts"| node_listener
node_listener -->|"starts workflow"| node_runner
node_alert_source -->|"submits alert"| node_rest_api
node_rest_api -->|"creates incident"| node_runner
node_runner -->|"executes workflow"| node_workflow_graph
node_runner -->|"tracks state"| node_workflow_state
node_workflow_graph -->|"recalls incidents"| node_incident_memory
node_workflow_graph -->|"retrieves runbook"| node_runbook_search
node_workflow_graph -->|"gathers evidence"| node_evidence_tools
node_workflow_graph -->|"evaluates incident"| node_decision_provider
node_workflow_graph -->|"requests approval"| node_approval
node_workflow_graph -->|"runs remediation"| node_remediation
node_workflow_graph -->|"stores outcome"| node_incident_memory
node_incident_memory -->|"reads and writes"| node_chroma
node_runbook_search -->|"searches vectors"| node_chroma
node_runbook_search -->|"uses embeddings"| node_embeddings
node_incident_memory -->|"uses embeddings"| node_embeddings
node_evidence_tools -->|"queries services"| node_simulated_environment
node_metrics -->|"queries metrics"| node_simulated_environment
node_remediation -->|"changes services"| node_simulated_environment
node_decision_provider -.->|"uses model adapter"| node_llm
node_workflow_graph -->|"uses retry logic"| node_reasoner
node_dashboard -->|"loads data"| node_api_client
node_incident_views -->|"fetches incident"| node_api_client
node_api_client -->|"calls endpoints"| node_rest_api
node_rest_api -->|"queries memory"| node_incident_memory
node_rest_api -->|"publishes alerts"| node_queue_helpers

click node_queue_helpers "https://github.com/zoro-zuro/incident-a/blob/main/agent/redis_queue.py"
click node_listener "https://github.com/zoro-zuro/incident-a/blob/main/agent/listener.py"
click node_rest_api "https://github.com/zoro-zuro/incident-a/blob/main/api/main.py"
click node_runner "https://github.com/zoro-zuro/incident-a/blob/main/agent/incident_runner.py"
click node_workflow_graph "https://github.com/zoro-zuro/incident-a/blob/main/agent/graph.py"
click node_workflow_state "https://github.com/zoro-zuro/incident-a/blob/main/agent/state.py"
click node_incident_memory "https://github.com/zoro-zuro/incident-a/blob/main/agent/memory.py"
click node_runbook_search "https://github.com/zoro-zuro/incident-a/blob/main/agent/rag.py"
click node_embeddings "https://github.com/zoro-zuro/incident-a/blob/main/agent/embeddings.py"
click node_evidence_tools "https://github.com/zoro-zuro/incident-a/blob/main/agent/tools.py"
click node_metrics "https://github.com/zoro-zuro/incident-a/blob/main/agent/metrics.py"
click node_simulated_environment "https://github.com/zoro-zuro/incident-a/blob/main/agent/simulated_env.py"
click node_decision_provider "https://github.com/zoro-zuro/incident-a/blob/main/agent/decision_provider.py"
click node_llm "https://github.com/zoro-zuro/incident-a/blob/main/agent/llm.py"
click node_reasoner "https://github.com/zoro-zuro/incident-a/blob/main/agent/reasoner.py"
click node_approval "https://github.com/zoro-zuro/incident-a/blob/main/agent/approval.py"
click node_remediation "https://github.com/zoro-zuro/incident-a/blob/main/agent/remediation.py"
click node_dashboard "https://github.com/zoro-zuro/incident-a/blob/main/frontend/src/App.tsx"
click node_api_client "https://github.com/zoro-zuro/incident-a/blob/main/frontend/src/lib/api.ts"
click node_incident_views "https://github.com/zoro-zuro/incident-a/blob/main/frontend/src/components/IncidentDetails.tsx"

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_redis,node_queue_helpers,node_listener toneBlue
class node_runner,node_workflow_graph,node_workflow_state,node_chroma toneAmber
class node_incident_memory,node_runbook_search,node_embeddings,node_evidence_tools,node_metrics,node_simulated_environment toneMint
class node_decision_provider,node_llm,node_reasoner,node_approval,node_remediation toneRose
class node_rest_api,node_dashboard,node_api_client,node_incident_views,node_alert_source toneIndigo
```

## Components

### Alert Ingestion

- **Redis Alerts**
- [Queue Helpers](https://github.com/zoro-zuro/incident-a/blob/main/agent/redis_queue.py): `agent/redis_queue.py`
- [Alert Listener](https://github.com/zoro-zuro/incident-a/blob/main/agent/listener.py): `agent/listener.py`

### Incident Workflow

- [Incident Runner](https://github.com/zoro-zuro/incident-a/blob/main/agent/incident_runner.py): `agent/incident_runner.py`
- [Workflow Orchestrator](https://github.com/zoro-zuro/incident-a/blob/main/agent/graph.py): `agent/graph.py`
- [Incident State](https://github.com/zoro-zuro/incident-a/blob/main/agent/state.py): `agent/state.py`

### Knowledge & Evidence

- [Incident Memory](https://github.com/zoro-zuro/incident-a/blob/main/agent/memory.py): `agent/memory.py`
- [Runbook Retrieval](https://github.com/zoro-zuro/incident-a/blob/main/agent/rag.py): `agent/rag.py`
- [Embedding Helper](https://github.com/zoro-zuro/incident-a/blob/main/agent/embeddings.py): `agent/embeddings.py`
- [Evidence Tools](https://github.com/zoro-zuro/incident-a/blob/main/agent/tools.py): `agent/tools.py`
- [Metrics Queries](https://github.com/zoro-zuro/incident-a/blob/main/agent/metrics.py): `agent/metrics.py`
- [Simulated Services](https://github.com/zoro-zuro/incident-a/blob/main/agent/simulated_env.py): `agent/simulated_env.py`

### Decision & Response

- [Decision Provider](https://github.com/zoro-zuro/incident-a/blob/main/agent/decision_provider.py): `agent/decision_provider.py`
- [LLM Adapter](https://github.com/zoro-zuro/incident-a/blob/main/agent/llm.py): `agent/llm.py`
- [Reasoning & Retry](https://github.com/zoro-zuro/incident-a/blob/main/agent/reasoner.py): `agent/reasoner.py`
- [Human Approval](https://github.com/zoro-zuro/incident-a/blob/main/agent/approval.py): `agent/approval.py`
- [Remediation](https://github.com/zoro-zuro/incident-a/blob/main/agent/remediation.py): `agent/remediation.py`

### API & Dashboard

- [REST API](https://github.com/zoro-zuro/incident-a/blob/main/api/main.py): `api/main.py`
- [React Dashboard](https://github.com/zoro-zuro/incident-a/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API Client](https://github.com/zoro-zuro/incident-a/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Incident Views](https://github.com/zoro-zuro/incident-a/blob/main/frontend/src/components/IncidentDetails.tsx): `frontend/src/components/IncidentDetails.tsx`

### Other components

- **Alert Source**
- **ChromaDB**

## Connections

- Alert Source → Redis Alerts: publishes alerts (evidence: `README.md`)
- Redis Alerts → Queue Helpers: delivers alerts (evidence: `README.md`)
- Queue Helpers → Alert Listener: dispatches alerts (evidence: `agent/listener.py`)
- Alert Listener → Incident Runner: starts workflow (evidence: `agent/listener.py`)
- Alert Source → REST API: submits alert (evidence: `README.md`)
- REST API → Incident Runner: creates incident (evidence: `api/main.py`)
- Incident Runner → Workflow Orchestrator: executes workflow (evidence: `agent/incident_runner.py`)
- Incident Runner → Incident State: tracks state (evidence: `agent/incident_runner.py`)
- Workflow Orchestrator → Incident Memory: recalls incidents (evidence: `agent/graph.py`)
- Workflow Orchestrator → Runbook Retrieval: retrieves runbook (evidence: `agent/graph.py`)
- Workflow Orchestrator → Evidence Tools: gathers evidence (evidence: `README.md`)
- Workflow Orchestrator → Decision Provider: evaluates incident (evidence: `agent/graph.py`)
- Workflow Orchestrator → Human Approval: requests approval (evidence: `agent/graph.py`)
- Workflow Orchestrator → Remediation: runs remediation (evidence: `README.md`)
- Workflow Orchestrator → Incident Memory: stores outcome (evidence: `README.md`)
- Incident Memory → ChromaDB: reads and writes (evidence: `agent/memory.py`)
- Runbook Retrieval → ChromaDB: searches vectors (evidence: `agent/rag.py`)
- Runbook Retrieval → Embedding Helper: uses embeddings (evidence: `agent/rag.py`)
- Incident Memory → Embedding Helper: uses embeddings (evidence: `agent/memory.py`)
- Evidence Tools → Simulated Services: queries services (evidence: `agent/tools.py`)
- Metrics Queries → Simulated Services: queries metrics (evidence: `agent/metrics.py`)
- Remediation → Simulated Services: changes services (evidence: `agent/remediation.py`)
- Decision Provider → LLM Adapter: uses model adapter
- Workflow Orchestrator → Reasoning & Retry: uses retry logic (evidence: `agent/graph.py`)
- React Dashboard → API Client: loads data (evidence: `frontend/src/App.tsx`)
- Incident Views → API Client: fetches incident (evidence: `frontend/src/components/IncidentDetails.tsx`)
- API Client → REST API: calls endpoints (evidence: `frontend/src/lib/api.ts`)
- REST API → Incident Memory: queries memory (evidence: `api/main.py`)
- REST API → Queue Helpers: publishes alerts (evidence: `api/main.py`)
