How danven-ong/incidentclue works
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: investigation.py LangGraph workflow · context.py Retrieval context · lifecycle.py Investigation lifecycle · App.tsx React app
Components 22
User interfaces
- React app
frontend/src/App.tsx - Create incident
frontend/src/NewIncident.tsx - Investigation view
frontend/src/Investigation.tsx - API client
frontend/src/api.ts
Application runtime
- FastAPI
backend/src/incidentclue/api/routes.py - Python CLI
backend/src/incidentclue/cli.py - Investigation lifecycle
backend/src/incidentclue/lifecycle.py - HTTP schemas
backend/src/incidentclue/api/schemas.py
Investigation engine
- LangGraph workflow
backend/src/incidentclue/investigation.py - Diagnosis generation
backend/src/incidentclue/diagnosis.py - Health and log tools
backend/src/incidentclue/tools.py - Domain models
backend/src/incidentclue/schemas.py - Groq LLM client
backend/src/incidentclue/llm.py
Runbook retrieval
- Retrieval context
backend/src/incidentclue/rag/context.py - Runbook corpus
backend/src/incidentclue/rag/corpus.py - Local embeddings
backend/src/incidentclue/rag/embeddings.py - Vector lookup
backend/src/incidentclue/rag/storage.py - Runbook documents
Durable state
- PostgreSQL
- Persistence and checkpoints
backend/src/incidentclue/persistence.py
Other components
- Browser user
- CLI user
Connections 27
- Browser user → React app: uses
- React app → Create incident: renders
frontend/src/App.tsx - React app → Investigation view: renders
frontend/src/App.tsx - Create incident → API client: requests
frontend/src/NewIncident.tsx - Investigation view → API client: requests
frontend/src/Investigation.tsx - API client → FastAPI: calls
frontend/src/api.ts - CLI user → Python CLI: uses
- Python CLI → Investigation lifecycle: invokes
backend/src/incidentclue/cli.py - FastAPI → Investigation lifecycle: invokes
backend/src/incidentclue/api/routes.py - FastAPI → HTTP schemas: validates
backend/src/incidentclue/api/routes.py - Investigation lifecycle → LangGraph workflow: runs
backend/src/incidentclue/lifecycle.py - Investigation lifecycle → Persistence and checkpoints: records state
backend/src/incidentclue/lifecycle.py - LangGraph workflow → Diagnosis generation: generates diagnosis
backend/src/incidentclue/investigation.py - LangGraph workflow → Health and log tools: dispatches tools
backend/src/incidentclue/investigation.py - LangGraph workflow → Retrieval context: requests guidance
backend/src/incidentclue/investigation.py - Diagnosis generation → Groq LLM client: requests completion
backend/src/incidentclue/diagnosis.py - Diagnosis generation → Domain models: validates output
backend/src/incidentclue/diagnosis.py - LangGraph workflow → Domain models: uses models
backend/src/incidentclue/investigation.py - Health and log tools → Domain models: uses models
backend/src/incidentclue/tools.py - Persistence and checkpoints → PostgreSQL: stores state
- LangGraph workflow → PostgreSQL: checkpoints
- Retrieval context → Runbook corpus: uses contracts
backend/src/incidentclue/rag/context.py - Retrieval context → Local embeddings: embeds queries
backend/src/incidentclue/rag/context.py - Retrieval context → Vector lookup: looks up passages
backend/src/incidentclue/rag/context.py - Vector lookup → PostgreSQL: reads and writes
backend/src/incidentclue/rag/storage.py - Runbook corpus → Runbook documents: loads documents
- Vector lookup → Local embeddings: embeds passages
backend/src/incidentclue/rag/storage.py