# bonzonkim/vmalert-webhook architecture

> Architecture diagram of the GitHub repository bonzonkim/vmalert-webhook, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bonzonkim/vmalert-webhook
- Repository: https://github.com/bonzonkim/vmalert-webhook

## Overview

##### Project type and purpose
- This is a single-purpose backend microservice written in Go.
- It receives webhook calls from Vmalert, queries VictoriaLogs for log details, and forwards formatted alerts to Slack.
- It is containerized (Docker) and deployed on Kubernetes.

##### File structure
Top-level folders:
- .github/workflows – CI pipeline definition (ci.yaml)
- kubernetes – Deployment and Service YAMLs for the webhook in-cluster
- src – All Go source, Dockerfile, env setup, test scripts
– main.go – Entry point, HTTP server exposing `/webhook`
– types/type.go – Data models for Vmalert payload and VictoriaLogs responses
– util/util.go – HTTP clients, common helpers (env reading, JSON marshalling)
– vlog/vlog.go – VictoriaLogs query builder and execution
– webhook/webhook.go – Core business logic: parse alert, call vlog, construct Slack payload, push to Slack
– Dockerfile – Container build instructions
– test.sh – Local test script to simulate an alert

##### Key points from README
- Expects environment variables: VICTORIALOGS_ENDPOINT, SLACK_ENDPOINT, optional VLOG_INGRESS
- Usage: `go run .` locally or `docker build` + `kubectl apply` with updated env in webhook-deployment.yaml
- Integration: configured as a webhook receiver in Prometheus Alertmanager

##### Components
1. Vmalert (Prometheus Vmalert) – emits alerts via HTTP POST to `/webhook`
2. Webhook Microservice (vmalert-webhook)
- HTTP server (main.go)
- Business logic layer (webhook.go)
- VictoriaLogs client (vlog.go)
- Utilities & types (util.go, type.go)
3. VictoriaLogs – external time-series + log service
4. Slack Incoming Webhook – external messaging endpoint
5. Kubernetes Cluster – Deployment + Service (kubernetes/webhook-*.yaml)
6. CI Pipeline – GitHub Actions for building, testing, pushing container

b. Relationships & Data Flow
1. Vmalert → (POST /webhook) → Webhook Microservice
2. Webhook Microservice → (HTTP query) → VictoriaLogs endpoint
3. VictoriaLogs → (JSON response) → Webhook Microservice
4. Webhook Microservice → (POST message) → Slack endpoint
5. Docker build pipeline from src/Dockerfile → Container Registry → Kubernetes Deployment
6. GitHub Actions CI triggers on push → build → test → push image

c. Architectural patterns & principles
- Single-responsibility microservice
- Clear separation of concerns: HTTP server vs. business logic vs. external client vs. data models
- Twelve-factor app principles: config via env vars, containerized, stateless
- Kubernetes-native deployment: use Deployment + Service for high-availability

d. Key technologies & libraries
- Go modules (go.mod/go.sum)
- net/http for server & clients
- Docker for containerization
- Kubernetes for orchestration
- GitHub Actions for CI

##### Diagramming recommendations
- Orange for infrastructure (Docker Registry, Kubernetes)
- Purple for CI pipeline

##### Final checklist
- Components: Vmalert, Webhook Service (with submodules), VictoriaLogs, Slack, Docker Registry, Kubernetes, CI
- Flows: Alert inbound, log query, alert outbound, container build & deploy, CI trigger
- Infrastructure boundaries (external vs. cluster vs. code modules)
- Call out any important configuration (env vars, ports, paths)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Alert Source
    VMA["Vmalert"]:::external

    %% Webhook Service Internal Components
    subgraph "Webhook Microservice" 
        direction TB
        SERVER["Webhook HTTP Server\n(/webhook)"]:::internal
        LOGIC["Business Logic Layer"]:::internal
        VLOGCLIENT["VictoriaLogs Client"]:::internal
        UTIL["Utilities & Helpers"]:::internal
        TYPES["Data Models"]:::internal
        MODULES["Go Modules\n(go.mod/go.sum)"]:::internal
        SCRIPT["Local Test Script"]:::internal
        SERVER -->|calls parse & handle| LOGIC
        LOGIC -->|uses| VLOGCLIENT
        LOGIC -->|uses| UTIL
        LOGIC -->|uses| TYPES
        UTIL -->|defined in| MODULES
        SERVER -->|invoke| SCRIPT
    end

    %% External Systems
    VICTORIALOGS["VictoriaLogs\n(HTTP API)"]:::external
    SLACK["Slack Incoming Webhook"]:::external

    %% Infra Components
    subgraph "Infrastructure" 
        direction TB
        REGISTRY["Docker Registry"]:::infra
        KUBEDEPLOY["Kubernetes Deployment"]:::infra
        KUBESVC["Kubernetes Service"]:::infra
    end

    %% CI Pipeline
    CI["GitHub Actions CI"]:::ci

    %% Data Flows
    VMA -->|HTTP POST /webhook| SERVER
    VLOGCLIENT -->|HTTP GET query| VICTORIALOGS
    VICTORIALOGS -->|JSON response| VLOGCLIENT
    LOGIC -->|HTTP POST message| SLACK
    MODULES -->|source| REGISTRY
    REGISTRY -->|image| KUBEDEPLOY
    KUBEDEPLOY -->|expose via| KUBESVC
    CI -->|build & test| MODULES
    CI -->|docker build/push| REGISTRY

    %% Click Events
    click SERVER "https://github.com/bonzonkim/vmalert-webhook/blob/main/src/main.go"
    click LOGIC "https://github.com/bonzonkim/vmalert-webhook/blob/main/src/webhook/webhook.go"
    click VLOGCLIENT "https://github.com/bonzonkim/vmalert-webhook/blob/main/src/vlog/vlog.go"
    click UTIL "https://github.com/bonzonkim/vmalert-webhook/blob/main/src/util/util.go"
    click TYPES "https://github.com/bonzonkim/vmalert-webhook/blob/main/src/types/type.go"
    click MODULES "https://github.com/bonzonkim/vmalert-webhook/blob/main/src/go.mod"
    click MODULES "https://github.com/bonzonkim/vmalert-webhook/blob/main/src/go.sum"
    click SCRIPT "https://github.com/bonzonkim/vmalert-webhook/blob/main/src/test.sh"
    click REGISTRY "https://github.com/bonzonkim/vmalert-webhook/tree/main/src/Dockerfile"
    click KUBEDEPLOY "https://github.com/bonzonkim/vmalert-webhook/blob/main/kubernetes/webhook-deployment.yaml"
    click KUBESVC "https://github.com/bonzonkim/vmalert-webhook/blob/main/kubernetes/webhook-service.yaml"
    click CI "https://github.com/bonzonkim/vmalert-webhook/blob/main/.github/workflows/ci.yaml"

    %% Styles
    classDef external fill:#9f6,stroke:#333,stroke-width:1px
    classDef internal fill:#6cf,stroke:#333,stroke-width:1px
    classDef infra fill:#f96,stroke:#333,stroke-width:1px
    classDef ci fill:#c6f,stroke:#333,stroke-width:1px
```
