# kubesphere/alert architecture

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

- Interactive diagram: https://gitdiagram.com/kubesphere/alert
- Repository: https://github.com/kubesphere/alert

## Overview

##### Project type and purpose
- This is a production-grade, distributed alerting system built in Go. It exposes gRPC/HTTP endpoints (API Gateway), manages alert policies (Manager), executes checks and notifications (Executor), and monitors service health and cluster state (Watcher). It persists state in MySQL and coordinates distributed tasks/locks via etcd.

##### File structure
- Top-level:
- cmd/alert: main entry point for the alert binary
- api/: protobuf definitions for all gRPC/HTTP APIs (with vendor’ed grpc-gateway swagger tooling)
- pkg/: reusable modules organized by component (apigateway, client SDK, db, etcd, manager, executor, watcher, notification, models, services, etc.)
- deploy/: k8s YAMLs for each service (manager, executor, watcher, API Gateway, etcd, MySQL)
- Dockerfile(.dev), Makefile: build and dev workflows
- pkg/db holds schema migrations, initialization scripts, and DDL.

##### Extract architectural insights from README/doc
- README calls out four logical services (API Gateway, Manager, Executor, Watcher) plus external dependencies (MySQL, etcd).

##### Main components and interactions
a. Clients / External Users
- HTTP/JSON or gRPC SDK clients (pkg/client)
- kubectl/CLI/webhook integrations
b. API Gateway
- grpc-gateway layer translating REST ↔ gRPC
- Swagger UI / OpenAPI spec for external consumption
c. Manager Service
- Loads alert policies, handles create/read/update/delete of alerts (uses pkg/services/manager)
- Places check tasks into a queue or etcd lock for Executors
- Reads/writes metadata to MySQL (pkg/db, pkg/models)
d. Executor Service
- Picks up scheduled checks (runner)
- Performs health checks and metric queries (pkg/services/executor)
- Reports results back to Manager or directly triggers notifications (pkg/notification)
e. Watcher Service
- Monitors liveness of Managers & Executors (health check loop)
- Maintains cluster state, triggers recovery or re-assignment upon failures
f. Infrastructure
- MySQL: stores schema under pkg/db/schema and migrations
- etcd: distributed lock manager, leader election, coordination (pkg/etcd)
- Kubernetes: all services run as Pods controlled by deploy/*.yaml

- Clients → API Gateway (REST/gRPC)
- API Gateway → Manager (gRPC)
- Manager → MySQL (SQL)
- Manager ↔ etcd (lock, election)
- Manager → Executor (task dispatch)
- Executor → Manager/Notification (results, notifications)
- Watcher → Manager/Executor (health probes)
- Watcher → etcd (coordination)

##### Architectural patterns and principles
- Microservices: clear separation of Gateway, Manager, Executor, Watcher
- Event-driven / task queue: Manager dispatches, Executor consumes
- Distributed coordination: etcd for leader election and locks
- Idempotent database migrations (pkg/db/schema)
- Protocol-first API design: protobuf + grpc-gateway + swagger

##### Relevant technologies & frameworks
- Go modules, gRPC, Protobuf
- grpc-gateway → REST fallback + OpenAPI/Swagger
- MySQL with migration scripts (Flyway-style naming)
- etcd client for distributed locking
- Kubernetes + Docker

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% External Clients
  subgraph "External Clients"
    Clients["Clients\n(pkg/client)"]:::external
  end

  %% Kubernetes Cluster
  subgraph "Kubernetes Cluster"
    direction TB

    subgraph "API Layer"
      direction TB
      APIG["API Gateway\n(pkg/apigateway)"]:::api
      PB["Protobuf API Definitions\n(api/)"]:::infra
    end

    subgraph "Core Services"
      direction TB
      MGR["Manager Service\n(pkg/services/manager)"]:::core
      EXE["Executor Service\n(pkg/services/executor)"]:::core
      WAT["Watcher Service\n(pkg/services/watcher)"]:::core
    end

    subgraph "Supporting Modules"
      direction TB
      MODELS["Core Data Models\n(pkg/models)"]:::infra
      NOTIF["Notification Module\n(pkg/notification)"]:::infra
    end

    subgraph "Datastores"
      direction TB
      MySQL["MySQL Database\n(pkg/db)"]:::db
      ETCD{"etcd Coordination\n(pkg/etcd)"}:::coord
    end
  end

  %% Connections
  Clients -->|HTTP/REST 8080<br/>gRPC 50051| APIG
  APIG -->|Uses gRPC| PB
  APIG -->|gRPC 50051| MGR
  MGR -->|SQL 3306| MySQL
  MGR -->|Lock/Election| ETCD
  MGR -->|Dispatch Tasks| EXE
  EXE -->|Results| MGR
  EXE -->|Trigger Notifications| NOTIF
  WAT -->|Health Probes| MGR
  WAT -->|Health Probes| EXE
  WAT -->|Coordination| ETCD
  MODELS --> MGR
  MODELS --> EXE
  MODELS --> WAT

  %% Click Events
  click APIG "https://github.com/kubesphere/alert/tree/master/pkg/apigateway"
  click MGR "https://github.com/kubesphere/alert/tree/master/pkg/services/manager"
  click EXE "https://github.com/kubesphere/alert/tree/master/pkg/services/executor"
  click WAT "https://github.com/kubesphere/alert/tree/master/pkg/services/watcher"
  click MySQL "https://github.com/kubesphere/alert/tree/master/pkg/db"
  click ETCD "https://github.com/kubesphere/alert/tree/master/pkg/etcd"
  click Clients "https://github.com/kubesphere/alert/tree/master/pkg/client"
  click MODELS "https://github.com/kubesphere/alert/tree/master/pkg/models"
  click NOTIF "https://github.com/kubesphere/alert/tree/master/pkg/notification"
  click PB "https://github.com/kubesphere/alert/tree/master/api/"

  %% Styles
  classDef external fill:#FFD700,stroke:#333,stroke-width:1px
  classDef api fill:#87CEEB,stroke:#333,stroke-width:1px
  classDef core fill:#98FB98,stroke:#333,stroke-width:1px
  classDef infra fill:#FFE4B5,stroke:#333,stroke-width:1px
  classDef db fill:#FA8072,stroke:#333,stroke-width:1px
  classDef coord fill:#DA70D6,stroke:#333,stroke-width:1px
```
