# stahir80td/incident-management architecture

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

- Interactive diagram: https://gitdiagram.com/stahir80td/incident-management
- Repository: https://github.com/stahir80td/incident-management

## Overview

##### Project Type & Purpose
- This is a backend‐centric, serverless RAG (Retrieval-Augmented Generation) service for automatic incident triage and enrichment.
- Offline: a Python ingestion pipeline builds a vector “knowledge base” from markdown incident reports.
- Online: Go‐based Vercel serverless functions receive PagerDuty webhooks, perform embedding→search→generation→notification, and expose a health endpoint.

##### File Structure Analysis
Top Level
- api/
– webhook.go (POST handler for PagerDuty webhooks)
– health.go (GET health check)
- create_incident.go, create_incidents.bat (CLI for generating dummy incidents)
- localserver.go, test_webhook.go (local dev & testing harness)
- services/ (abstractions over external APIs)
– gemini.go (Google Gemini embedding & LLM calls)
– qdrant.go (vector DB interactions)
– pagerduty.go (PagerDuty REST calls)
– rag.go (pipeline orchestration)
- incidents/ (raw Markdown incident history)
- ingest_incidents.py (+ requirements.txt) (Python RAG ingestion pipeline)
- go.mod / go.sum, env.example, vercel.json

##### Key Architecture Insights from README
- Offline “Phase 1”: ingest Markdown → chunk → embed via Gemini → store vectors in Qdrant
- Online “Phase 2”: PagerDuty → webhook → embed new incident → search top-k in Qdrant → generate triage note via Gemini LLM → post note back to PagerDuty
- Tech Stack: Go1.21 serverless on Vercel; Python3.11 ingestion; Qdrant Cloud; Google Gemini (embeddings + LLM)

##### Main Components
1. PagerDuty (Incident Trigger → Generic Webhook v3)
2. Vercel Serverless Platform (hosting Go functions)
3. Google Gemini API (embeddings & LLM)
4. Qdrant Cloud Vector DB
B. Internal Compute
1. /api/webhook function (Go): parses payload, returns 202 immediately
2. RAG Pipeline orchestrator (services/rag.go)
– Embedding Generation (services/gemini.go → Gemini REST)
– Semantic Search (services/qdrant.go → Qdrant REST)
– Contextual Prompt Building
– LLM Generation (services/gemini.go → Gemini LLM)
3. /api/health function (Go)
C. Offline Ingestion Pipeline
– ingest_incidents.py (Python): reads incidents/*.md, chunks, calls Gemini embeddings, writes to Qdrant
D. Data Stores & Artifacts
– incidents/*.md (source corpus)
– Qdrant collection (vector store)
E. Notification Target
– PagerDuty API (POST note to incident)

##### Relationships & Data Flow
1. PagerDuty fires webhook → HTTP POST to /api/webhook
2. Go function immediately 202s, enqueues or directly invokes RAG steps
3. Generate embedding via Gemini → send vector to Qdrant → receive top-3 matches
4. Build prompt with new incident + matched incident context → send to Gemini LLM → receive triage note
5. Call PagerDuty API to attach note
6. Meanwhile, offline ingestion script periodically updates Qdrant with new incident vectors

##### Architectural Patterns & Principles
- Serverless microservice decomposition (each endpoint is a separate function)
- Asynchronous/Non-blocking response for inbound webhook
- RAG pattern: Retrieval (vector search) + Generation (LLM)
- Clear separation: offline vs online pipelines
- Single responsibility modules (services/*)

## Diagram (Mermaid)

```mermaid
flowchart TB
    classDef external fill:#dddddd,stroke:#888;
    classDef internal fill:#bbdefb,stroke:#1e88e5;
    classDef datastore fill:#c8e6c9,stroke:#2e7d32;
    classDef files fill:#fff9c4,stroke:#f9a825;

    subgraph "Production Environment"
        direction TB
        PDuty["PagerDuty\n(Webhook Source)"]:::external
        webhook["Webhook Handler\n(api/webhook.go)"]:::internal
        health["Health Check\n(api/health.go)"]:::internal
        orchestrator["RAG Orchestrator\n(services/rag.go)"]:::internal
        gemini["Google Gemini Client\n(services/gemini.go)"]:::external
        qdrant["Qdrant Client\n(services/qdrant.go)"]:::internal
        pagerdutyClient["PagerDuty API Client\n(services/pagerduty.go)"]:::external
        db["Qdrant Vector DB"]:::datastore
    end

    subgraph "Offline Ingestion"
        direction TB
        corpus["Incident Corpus\n(incidents/*.md)"]:::files
        ingest["Ingestion Pipeline\n(ingest_incidents.py)"]:::internal
    end

    subgraph "Utilities"
        direction TB
        createCLI["CLI Tools\n(create_incident.go,\ncreate_incidents.bat)"]:::internal
        localDev["Dev Harness\n(localserver.go,\ntest_webhook.go)"]:::internal
        config["Env Config\n(env.example)"]:::files
        deployCfg["Vercel Config\n(vercel.json)"]:::files
        modules["Go Modules\n(go.mod,\ngo.sum)"]:::files
    end

    PDuty -->|"1. webhook"| webhook
    webhook -->|"2. orchestrator"| orchestrator
    orchestrator -->|"Embed"| gemini
    gemini -->|"Vector"| qdrant
    qdrant -->|"Top-k vectors"| orchestrator
    orchestrator -->|"Generate"| gemini
    gemini -->|"Triage Note"| orchestrator
    orchestrator -->|"Notify"| pagerdutyClient
    pagerdutyClient -->|"POST note"| PDuty

    PDuty -.->|"Health Check"| health

    corpus --> ingest
    ingest -->|"Embed & Store"| gemini
    gemini --> db

    click webhook "https://github.com/stahir80td/incident-management/blob/main/api/webhook.go"
    click health "https://github.com/stahir80td/incident-management/blob/main/api/health.go"
    click orchestrator "https://github.com/stahir80td/incident-management/blob/main/services/rag.go"
    click gemini "https://github.com/stahir80td/incident-management/blob/main/services/gemini.go"
    click qdrant "https://github.com/stahir80td/incident-management/blob/main/services/qdrant.go"
    click pagerdutyClient "https://github.com/stahir80td/incident-management/blob/main/services/pagerduty.go"
    click ingest "https://github.com/stahir80td/incident-management/blob/main/ingest_incidents.py"
    click corpus "https://github.com/stahir80td/incident-management/blob/main/incidents/*.md"
    click createCLI "https://github.com/stahir80td/incident-management/blob/main/create_incident.go"
    click localDev "https://github.com/stahir80td/incident-management/blob/main/localserver.go"
    click config "https://github.com/stahir80td/incident-management/blob/main/env.example"
    click deployCfg "https://github.com/stahir80td/incident-management/blob/main/vercel.json"
    click modules "https://github.com/stahir80td/incident-management/blob/main/go.mod"
```
