# danven-ong/incidentclue architecture

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

- Interactive diagram: https://gitdiagram.com/danven-ong/incidentclue
- Repository: https://github.com/danven-ong/incidentclue

## Overview

IncidentClue investigates recorded service-health and log evidence, returning a structured, evidence-linked diagnosis with uncertainty and optional separately cited runbook guidance. Users create and inspect investigations in the React UI, through the REST API, or via the CLI; the API and CLI share a durable lifecycle that runs a bounded LangGraph investigation and checkpoints progress in PostgreSQL. The README documents the main runtime connections; source-index references and excerpts support internal calls shown here. RAG internals are represented, but some wiring is documented rather than directly excerpted.

Main entry points: [`backend/src/incidentclue/investigation.py`](https://github.com/danven-ong/incidentclue/blob/main/backend/src/incidentclue/investigation.py) (LangGraph workflow), [`backend/src/incidentclue/rag/context.py`](https://github.com/danven-ong/incidentclue/blob/main/backend/src/incidentclue/rag/context.py) (Retrieval context), [`backend/src/incidentclue/lifecycle.py`](https://github.com/danven-ong/incidentclue/blob/main/backend/src/incidentclue/lifecycle.py) (Investigation lifecycle), [`frontend/src/App.tsx`](https://github.com/danven-ong/incidentclue/blob/main/frontend/src/App.tsx) (React app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User interfaces"]
  node_web_app["React app<br/>[App.tsx]"]
  node_new_incident["Create incident<br/>[NewIncident.tsx]"]
  node_investigation_view["Investigation view<br/>[Investigation.tsx]"]
  node_web_api["API client<br/>[api.ts]"]
end

subgraph group_runtime["Application runtime"]
  node_rest_api["FastAPI<br/>[routes.py]"]
  node_cli["Python CLI<br/>[cli.py]"]
  node_lifecycle["Investigation lifecycle<br/>[lifecycle.py]"]
  node_api_schemas["HTTP schemas<br/>[schemas.py]"]
end

subgraph group_engine["Investigation engine"]
  node_graph["LangGraph workflow<br/>[investigation.py]"]
  node_diagnosis["Diagnosis generation<br/>[diagnosis.py]"]
  node_evidence_tools["Health and log tools<br/>[tools.py]"]
  node_domain_schemas["Domain models<br/>[schemas.py]"]
  node_llm_client["Groq LLM client<br/>[llm.py]"]
end

subgraph group_rag["Runbook retrieval"]
  node_rag_context["Retrieval context<br/>[context.py]"]
  node_corpus["Runbook corpus<br/>[corpus.py]"]
  node_embeddings["Local embeddings<br/>[embeddings.py]"]
  node_rag_storage["Vector lookup<br/>[storage.py]"]
  node_runbooks["Runbook documents"]
end

subgraph group_storage["Durable state"]
  node_postgres[("PostgreSQL")]
  node_persistence["Persistence and checkpoints<br/>[persistence.py]"]
end

node_browser_user(("Browser user"))
node_cli_user(("CLI user"))

node_browser_user -->|"uses"| node_web_app
node_web_app -->|"renders"| node_new_incident
node_web_app -->|"renders"| node_investigation_view
node_new_incident -->|"requests"| node_web_api
node_investigation_view -->|"requests"| node_web_api
node_web_api -->|"calls"| node_rest_api
node_cli_user -->|"uses"| node_cli
node_cli -->|"invokes"| node_lifecycle
node_rest_api -->|"invokes"| node_lifecycle
node_rest_api -->|"validates"| node_api_schemas
node_lifecycle -->|"runs"| node_graph
node_lifecycle -->|"records state"| node_persistence
node_graph -->|"generates diagnosis"| node_diagnosis
node_graph -->|"dispatches tools"| node_evidence_tools
node_graph -->|"requests guidance"| node_rag_context
node_diagnosis -->|"requests completion"| node_llm_client
node_diagnosis -->|"validates output"| node_domain_schemas
node_graph -->|"uses models"| node_domain_schemas
node_evidence_tools -->|"uses models"| node_domain_schemas
node_persistence -->|"stores state"| node_postgres
node_graph -->|"checkpoints"| node_postgres
node_rag_context -->|"uses contracts"| node_corpus
node_rag_context -->|"embeds queries"| node_embeddings
node_rag_context -->|"looks up passages"| node_rag_storage
node_rag_storage -->|"reads and writes"| node_postgres
node_corpus -.->|"loads documents"| node_runbooks
node_rag_storage -->|"embeds passages"| node_embeddings

click node_web_app "https://github.com/danven-ong/incidentclue/blob/main/frontend/src/App.tsx"
click node_new_incident "https://github.com/danven-ong/incidentclue/blob/main/frontend/src/NewIncident.tsx"
click node_investigation_view "https://github.com/danven-ong/incidentclue/blob/main/frontend/src/Investigation.tsx"
click node_web_api "https://github.com/danven-ong/incidentclue/blob/main/frontend/src/api.ts"
click node_rest_api "https://github.com/danven-ong/incidentclue/blob/main/backend/src/incidentclue/api/routes.py"
click node_cli "https://github.com/danven-ong/incidentclue/blob/main/backend/src/incidentclue/cli.py"
click node_lifecycle "https://github.com/danven-ong/incidentclue/blob/main/backend/src/incidentclue/lifecycle.py"
click node_api_schemas "https://github.com/danven-ong/incidentclue/blob/main/backend/src/incidentclue/api/schemas.py"
click node_graph "https://github.com/danven-ong/incidentclue/blob/main/backend/src/incidentclue/investigation.py"
click node_diagnosis "https://github.com/danven-ong/incidentclue/blob/main/backend/src/incidentclue/diagnosis.py"
click node_evidence_tools "https://github.com/danven-ong/incidentclue/blob/main/backend/src/incidentclue/tools.py"
click node_domain_schemas "https://github.com/danven-ong/incidentclue/blob/main/backend/src/incidentclue/schemas.py"
click node_llm_client "https://github.com/danven-ong/incidentclue/blob/main/backend/src/incidentclue/llm.py"
click node_persistence "https://github.com/danven-ong/incidentclue/blob/main/backend/src/incidentclue/persistence.py"
click node_rag_context "https://github.com/danven-ong/incidentclue/blob/main/backend/src/incidentclue/rag/context.py"
click node_corpus "https://github.com/danven-ong/incidentclue/blob/main/backend/src/incidentclue/rag/corpus.py"
click node_embeddings "https://github.com/danven-ong/incidentclue/blob/main/backend/src/incidentclue/rag/embeddings.py"
click node_rag_storage "https://github.com/danven-ong/incidentclue/blob/main/backend/src/incidentclue/rag/storage.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_web_app,node_new_incident,node_investigation_view,node_web_api,node_browser_user,node_cli_user toneBlue
class node_rest_api,node_cli,node_lifecycle,node_api_schemas toneAmber
class node_graph,node_diagnosis,node_evidence_tools,node_domain_schemas,node_llm_client toneMint
class node_rag_context,node_corpus,node_embeddings,node_rag_storage,node_runbooks toneRose
class node_postgres,node_persistence toneIndigo
```

## Components

### User interfaces

- [React app](https://github.com/danven-ong/incidentclue/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Create incident](https://github.com/danven-ong/incidentclue/blob/main/frontend/src/NewIncident.tsx): `frontend/src/NewIncident.tsx`
- [Investigation view](https://github.com/danven-ong/incidentclue/blob/main/frontend/src/Investigation.tsx): `frontend/src/Investigation.tsx`
- [API client](https://github.com/danven-ong/incidentclue/blob/main/frontend/src/api.ts): `frontend/src/api.ts`

### Application runtime

- [FastAPI](https://github.com/danven-ong/incidentclue/blob/main/backend/src/incidentclue/api/routes.py): `backend/src/incidentclue/api/routes.py`
- [Python CLI](https://github.com/danven-ong/incidentclue/blob/main/backend/src/incidentclue/cli.py): `backend/src/incidentclue/cli.py`
- [Investigation lifecycle](https://github.com/danven-ong/incidentclue/blob/main/backend/src/incidentclue/lifecycle.py): `backend/src/incidentclue/lifecycle.py`
- [HTTP schemas](https://github.com/danven-ong/incidentclue/blob/main/backend/src/incidentclue/api/schemas.py): `backend/src/incidentclue/api/schemas.py`

### Investigation engine

- [LangGraph workflow](https://github.com/danven-ong/incidentclue/blob/main/backend/src/incidentclue/investigation.py): `backend/src/incidentclue/investigation.py`
- [Diagnosis generation](https://github.com/danven-ong/incidentclue/blob/main/backend/src/incidentclue/diagnosis.py): `backend/src/incidentclue/diagnosis.py`
- [Health and log tools](https://github.com/danven-ong/incidentclue/blob/main/backend/src/incidentclue/tools.py): `backend/src/incidentclue/tools.py`
- [Domain models](https://github.com/danven-ong/incidentclue/blob/main/backend/src/incidentclue/schemas.py): `backend/src/incidentclue/schemas.py`
- [Groq LLM client](https://github.com/danven-ong/incidentclue/blob/main/backend/src/incidentclue/llm.py): `backend/src/incidentclue/llm.py`

### Runbook retrieval

- [Retrieval context](https://github.com/danven-ong/incidentclue/blob/main/backend/src/incidentclue/rag/context.py): `backend/src/incidentclue/rag/context.py`
- [Runbook corpus](https://github.com/danven-ong/incidentclue/blob/main/backend/src/incidentclue/rag/corpus.py): `backend/src/incidentclue/rag/corpus.py`
- [Local embeddings](https://github.com/danven-ong/incidentclue/blob/main/backend/src/incidentclue/rag/embeddings.py): `backend/src/incidentclue/rag/embeddings.py`
- [Vector lookup](https://github.com/danven-ong/incidentclue/blob/main/backend/src/incidentclue/rag/storage.py): `backend/src/incidentclue/rag/storage.py`
- **Runbook documents**

### Durable state

- **PostgreSQL**
- [Persistence and checkpoints](https://github.com/danven-ong/incidentclue/blob/main/backend/src/incidentclue/persistence.py): `backend/src/incidentclue/persistence.py`

### Other components

- **Browser user**
- **CLI user**

## Connections

- Browser user → React app: uses
- React app → Create incident: renders (evidence: `frontend/src/App.tsx`)
- React app → Investigation view: renders (evidence: `frontend/src/App.tsx`)
- Create incident → API client: requests (evidence: `frontend/src/NewIncident.tsx`)
- Investigation view → API client: requests (evidence: `frontend/src/Investigation.tsx`)
- API client → FastAPI: calls (evidence: `frontend/src/api.ts`)
- CLI user → Python CLI: uses
- Python CLI → Investigation lifecycle: invokes (evidence: `backend/src/incidentclue/cli.py`)
- FastAPI → Investigation lifecycle: invokes (evidence: `backend/src/incidentclue/api/routes.py`)
- FastAPI → HTTP schemas: validates (evidence: `backend/src/incidentclue/api/routes.py`)
- Investigation lifecycle → LangGraph workflow: runs (evidence: `backend/src/incidentclue/lifecycle.py`)
- Investigation lifecycle → Persistence and checkpoints: records state (evidence: `backend/src/incidentclue/lifecycle.py`)
- LangGraph workflow → Diagnosis generation: generates diagnosis (evidence: `backend/src/incidentclue/investigation.py`)
- LangGraph workflow → Health and log tools: dispatches tools (evidence: `backend/src/incidentclue/investigation.py`)
- LangGraph workflow → Retrieval context: requests guidance (evidence: `backend/src/incidentclue/investigation.py`)
- Diagnosis generation → Groq LLM client: requests completion (evidence: `backend/src/incidentclue/diagnosis.py`)
- Diagnosis generation → Domain models: validates output (evidence: `backend/src/incidentclue/diagnosis.py`)
- LangGraph workflow → Domain models: uses models (evidence: `backend/src/incidentclue/investigation.py`)
- Health and log tools → Domain models: uses models (evidence: `backend/src/incidentclue/tools.py`)
- Persistence and checkpoints → PostgreSQL: stores state
- LangGraph workflow → PostgreSQL: checkpoints
- Retrieval context → Runbook corpus: uses contracts (evidence: `backend/src/incidentclue/rag/context.py`)
- Retrieval context → Local embeddings: embeds queries (evidence: `backend/src/incidentclue/rag/context.py`)
- Retrieval context → Vector lookup: looks up passages (evidence: `backend/src/incidentclue/rag/context.py`)
- Vector lookup → PostgreSQL: reads and writes (evidence: `backend/src/incidentclue/rag/storage.py`)
- Runbook corpus → Runbook documents: loads documents
- Vector lookup → Local embeddings: embeds passages (evidence: `backend/src/incidentclue/rag/storage.py`)
