# opsre/watchalert architecture

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

- Interactive diagram: https://gitdiagram.com/opsre/watchalert
- Repository: https://github.com/opsre/watchalert

## Overview

##### Main components
- Alert Engine Modules: These are primarily under the “alert” directory and include submodules for alert consumption, evaluation (eval), mute, probing, process, and storage. Each subcomponent deals with different parts of alert handling & processing.
- API Layer: The “api” directory contains many files for endpoints (e.g., dashboard, event, user, rule management, notifications) that expose the system’s functionalities to users and external clients.
- Internal Core & Services: Under “internal” you have caches, middleware, models, repositories, routers, and services. These components handle business logic such as auditing, authentication, tenant management, and data persistence.
- Providers & External Integration: The “pkg/provider” and “pkg/community” directories integrate with third-party systems (e.g., AWS Cloudwatch, Kubernetes, various monitoring tools). They encapsulate connectivity to data sources.
- Notification & Template Senders: In “pkg/sender” and “pkg/templates”, there are integrations for sending alerts as notifications (via email, Dingding, WeChat, Feishu, custom webhooks, or phone calls).
- Initialization & Configuration: “initialization” and “config” provide app startup routines, routing configuration, and overall configuration management.
- Deployment & Infrastructure: The “deploy” directory (including docker-compose and Kubernetes YAMLs, plus SQL scripts) gives insights into how the system is containerized and managed in production.

##### Relationships and interactions between components
- Data Sources & Providers: Start by showing external monitoring tools, cloud services, and network probes that feed data. These will connect into the “pkg/provider” and “pkg/community” modules.
- Alert Processing Pipeline: Data flows into the Alert Engine (components under “alert”) where alerts are consumed, evaluated (with AI analysis), processed (including muting and probing), and finally stored.
- API Exposure: The API layer (“api” and “internal/routers/v1”) exposes functionalities for configuration, alert management, dashboards, user management, and more. It interacts with the underlying core (internal models, repositories, and services).
- Notification Dispatch: Once an alert is processed, notifications are sent out through the “pkg/sender” modules based on user configurations and preferences.
- Configuration and Middleware: Global settings/control provided via “config” and “internal/middleware” manage cross-cutting concerns such as logging, authentication, auditing, CORS, and permissions.
- Deployment/Containerization: Represent how the components are packaged and orchestrated using Docker (Dockerfile, docker-compose) and Kubernetes (in deploy/kubernetes).

##### Architectural patterns/design principles
- Layered Architecture: Separation between data ingestion, business logic, and API presentation layers.
- Modular Design: Each core function (alert evaluation, processing, notification dispatch) is contained in its own module.
- Integration of Third-Party Services: The project abstracts integrations (metrics, logs, traces, network probes) into dedicated provider packages.
- Configurability & Extensibility: Directories like “config”, “deploy”, and “pkg/templates” indicate a design that allows easy extension and configuration for different environments.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Data Sources
    external["External Data Sources"]:::external

    %% Providers & External Integration
    subgraph "Providers & External Integration"
        provider["pkg/provider"]:::provider
        community["pkg/community"]:::provider
    end

    %% Alert Engine Modules
    subgraph "Alert Engine Modules"
        consumer["alert/consumer"]:::alert
        eval["alert/eval"]:::alert
        mute["alert/mute"]:::alert
        probing["alert/probing"]:::alert
        process["alert/process"]:::alert
        storage["alert/storage"]:::alert
    end

    %% API Layer
    subgraph "API Layer"
        api["api"]:::api
        routers["internal/routers/v1"]:::api
    end

    %% Internal Core & Services
    subgraph "Internal Core & Services"
        models["internal/models"]:::internal
        services["internal/services"]:::internal
        repo["internal/repo"]:::internal
        middleware["internal/middleware"]:::internal
    end

    %% Notification & Alert Dispatch
    subgraph "Notification & Alert Dispatch"
        sender["pkg/sender"]:::notification
        templates["pkg/templates"]:::notification
    end

    %% Initialization & Configuration
    subgraph "Initialization & Configuration"
        init["initialization"]:::config
        configNode["config"]:::config
    end

    %% Deployment & Infrastructure
    subgraph "Deployment & Infrastructure"
        deploy["deploy"]:::deployment
    end

    %% Connections
    external --> provider
    external --> community

    provider --> consumer
    community --> consumer

    consumer -->|"consumes"| eval
    eval -->|"evaluates"| process
    eval -->|"triggers_mute"| mute
    eval -->|"initiates_probing"| probing
    process -->|"stores_alerts"| storage
    process -->|"sends_notifications"| sender

    sender -->|"uses_templates"| templates

    %% API and Internal interactions
    api --> routers
    routers --> services
    services --> models
    services --> repo
    services --> middleware
    routers -->|"fetches_alerts"| consumer
    services -->|"triggers_eval"| eval

    %% Configuration links
    init --> configNode
    configNode --> middleware
    configNode --> services

    %% Deployment integration (Deployment oversees initialization)
    deploy --> init

    %% Class Definitions for Colour Coding
    classDef external fill:#f4cccc,stroke:#000,stroke-width:2px;
    classDef provider fill:#c9daf8,stroke:#000,stroke-width:2px;
    classDef alert fill:#d9ead3,stroke:#000,stroke-width:2px;
    classDef api fill:#fff2cc,stroke:#000,stroke-width:2px;
    classDef internal fill:#ead1dc,stroke:#000,stroke-width:2px;
    classDef notification fill:#d9d2e9,stroke:#000,stroke-width:2px;
    classDef config fill:#cfe2f3,stroke:#000,stroke-width:2px;
    classDef deployment fill:#fce5cd,stroke:#000,stroke-width:2px;

    %% Click Events for Alert Engine Modules
    click consumer "https://github.com/opsre/watchalert/tree/master/alert/consumer"
    click eval "https://github.com/opsre/watchalert/tree/master/alert/eval"
    click mute "https://github.com/opsre/watchalert/tree/master/alert/mute"
    click probing "https://github.com/opsre/watchalert/tree/master/alert/probing"
    click process "https://github.com/opsre/watchalert/tree/master/alert/process"
    click storage "https://github.com/opsre/watchalert/tree/master/alert/storage"

    %% Click Events for API Layer
    click api "https://github.com/opsre/watchalert/tree/master/api"
    click routers "https://github.com/opsre/watchalert/tree/master/internal/routers/v1"

    %% Click Events for Internal Core & Services
    click models "https://github.com/opsre/watchalert/tree/master/internal/models"
    click services "https://github.com/opsre/watchalert/tree/master/internal/services"
    click repo "https://github.com/opsre/watchalert/tree/master/internal/repo"
    click middleware "https://github.com/opsre/watchalert/tree/master/internal/middleware"

    %% Click Events for Providers & External Integration
    click provider "https://github.com/opsre/watchalert/tree/master/pkg/provider"
    click community "https://github.com/opsre/watchalert/tree/master/pkg/community"

    %% Click Events for Notification & Alert Dispatch
    click sender "https://github.com/opsre/watchalert/tree/master/pkg/sender"
    click templates "https://github.com/opsre/watchalert/tree/master/pkg/templates"

    %% Click Events for Initialization & Configuration
    click init "https://github.com/opsre/watchalert/tree/master/initialization"
    click configNode "https://github.com/opsre/watchalert/tree/master/config"

    %% Click Event for Deployment & Infrastructure
    click deploy "https://github.com/opsre/watchalert/tree/master/deploy"
```
