# ccfos/nightingale architecture

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

- Interactive diagram: https://gitdiagram.com/ccfos/nightingale
- Repository: https://github.com/ccfos/nightingale

## Overview

##### Project Type & Purpose
- Nightingale is an open‐source cloud native monitoring and alert management system. It focuses on collecting metrics from multiple time‐series databases (Prometheus, VictoriaMetrics, TDengine, etc.), evaluating alerting rules, dispatching notifications, and providing a unified management interface.
- The README emphasizes its role as a “告警管理专家” (expert in alert management) and explains that it integrates with various data sources and even supports edge deployment scenarios.

##### Analyzing the File Structure
- The top-level directories – such as “alert”, “center”, “cli”, “cmd”, “datasource”, “integrations”, “pushgw”, “memsto”, “pkg”, “models”, and “storage” – reflect a strong separation of concerns.
- The “alert” directory contains modules for rule evaluation (eval), dispatching alert events, notification senders, alert processing, muting of alerts, queues, and record keeping.
- The “center” directory seems to handle configuration management, API routing (many router submodules), SSO, integration endpoints, and statistics, indicating it is the central control plane for the alert system.
- “cmd” contains multiple executable service entrypoints for alert, center, push gateway (pushgw), edge services, and CLI tools.
- “datasource” and “integrations” provide connectors and dashboards for external systems, while “docker”, “conf”, and “etc” show deployment and configuration aspects.
- Other utility directories such as “pkg” and “models” estimate supportive libraries and data models, respectively.

##### Core Components & Their Relationships
- Alert Engine Service:
- Submodules: rule evaluation (alert/eval), alert dispatching (alert/dispatch), alert processing (alert/process), queues (alert/queue), and notification senders (alert/sender).
- Role: Evaluates alert rules, processes alert events, and dispatches notifications through various channels.
- Center Service (Central Management and API Gateway):
- Contains configuration handling, web API routing (center/router), statistics (center/cstats), and integrations.
- Role: Acts as the central control plane for managing alert rules, dashboards, user accounts, and integrations.
- Push Gateway (pushgw):
- Handles receiving metrics or alert events (including using Kafka producers, relabeling, etc.) and “pushing” them to appropriate queues or downstream systems.
- CLI and Upgrade Tools (cli & cmd/cli):
- Provide administrative tools for command-line management, upgrades, and configuration synchronization.
- Edge Service (cmd/edge):
- Supports deployment in edge environments (when connectivity to the central service might be intermittent), ensuring alert functionality remains available.
- Integrations:
- The “integrations” folder contains specific connectors, dashboards, and alert rules for a range of third-party systems, which extend Nightingale’s capabilities.
- Data Sources & Storage:
- “datasource” connectors support different time-series data backends, while “storage” and “memsto” manage caching/database interactions.

##### Architectural Patterns / Design Principles
- Modular / Microservice-like Organization: Each major domain (alert processing, central management, push gateway) is clearly separated into its own command and module directories.
- Separation of Concerns: Frontend (in “front”) and backend are segregated, with the backend divided among alert evaluation, configuration management, and message dispatch.
- Plug-in Architecture: The alert sender modules and integration connectors indicate extensibility using plugins for different notification channels and data sources.
- Scalability & Resilience: The presence of edge deployment (cmd/edge) and use of queues, along with multiple data sources and aggregation via the center service, shows distributed design geared for high availability.

##### Final Advice
- Be very detailed—explore the functions within each main module. Know that splitting the overall design into as many clearly defined smaller components (i.e., microservices or modules) as possible will best illustrate the complexity of Nightingale.
- Tie the component interactions back to the alerts workflow: data collection (datasource/integrations) → rule evaluation (alert/eval) → dispatch (alert/dispatch, pushgw) → notification (alert/sender) → centralized management (center).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Collection
    subgraph "Data Collection"
        DS["datasource"]:::datasource
        IN["integrations"]:::integration
    end

    %% Alert Engine Service
    subgraph "Alert Engine Service"
        AE_EVAL["alert/eval"]:::alertEngine
        AE_PROC["alert/process"]:::alertEngine
        AE_DISP["alert/dispatch"]:::alertEngine
        AE_QUEUE["alert/queue"]:::alertEngine
        AE_SENDER["alert/sender"]:::alertEngine
    end

    %% Push Gateway Service
    subgraph "Push Gateway Service"
        PG_ROUTER["pushgw/router"]:::pushGateway
        PG_WRITER["pushgw/writer"]:::pushGateway
    end

    %% Center Service
    subgraph "Center Service"
        C_ROUTER["center/router"]:::centerService
        C_CSTATS["center/cstats"]:::centerService
        C_SSO["center/sso"]:::centerService
    end

    %% CLI Tools
    subgraph "CLI Tools"
        CLI1["cli"]:::cliTools
        CLI2["cmd/cli"]:::cliTools
    end

    %% Edge Service
    EDGE["cmd/edge (Edge Service)"]:::edgeService

    %% Support Libraries
    subgraph "Support Libraries"
        PKG["pkg"]:::support
        MODELS["models"]:::support
    end

    %% Caching & Persistent Storage
    CACHE["memsto (Caching)"]:::caching
    STORAGE["storage (Persistent Storage)"]:::storage

    %% Connections: Data Flow
    DS -->|"feeds"| AE_EVAL
    IN -->|"alerts"| AE_EVAL

    AE_EVAL -->|"process"| AE_PROC
    AE_PROC -->|"dispatch"| AE_DISP
    AE_PROC -->|"queue"| AE_QUEUE
    AE_DISP -->|"notify"| AE_SENDER

    AE_DISP -->|"push"| PG_ROUTER
    PG_ROUTER -->|"write"| PG_WRITER

    PG_WRITER -->|"control"| C_ROUTER

    %% Connections: Control & Update Flow
    CLI1 -->|"update"| C_ROUTER
    CLI2 -->|"config_sync"| C_CSTATS

    EDGE -->|"fallback"| C_ROUTER
    EDGE -->|"local_alert"| AE_EVAL

    %% Connections: Supporting Libraries and Storage
    PKG -.-> AE_EVAL
    PKG -.-> C_ROUTER
    MODELS -.-> AE_EVAL
    MODELS -.-> C_SSO

    CACHE -.-> AE_QUEUE
    CACHE -.-> C_CSTATS

    STORAGE -.-> C_CSTATS
    STORAGE -.-> AE_SENDER

    %% Click Events
    click DS "https://github.com/ccfos/nightingale/tree/main/datasource"
    click IN "https://github.com/ccfos/nightingale/tree/main/integrations"
    click AE_EVAL "https://github.com/ccfos/nightingale/tree/main/alert"
    click PG_ROUTER "https://github.com/ccfos/nightingale/tree/main/pushgw"
    click C_ROUTER "https://github.com/ccfos/nightingale/tree/main/center"
    click CLI1 "https://github.com/ccfos/nightingale/tree/main/cli"
    click CLI2 "https://github.com/ccfos/nightingale/tree/main/cmd/cli"
    click EDGE "https://github.com/ccfos/nightingale/tree/main/cmd/edge"
    click PKG "https://github.com/ccfos/nightingale/tree/main/pkg"
    click MODELS "https://github.com/ccfos/nightingale/tree/main/models"
    click CACHE "https://github.com/ccfos/nightingale/tree/main/memsto"
    click STORAGE "https://github.com/ccfos/nightingale/tree/main/storage"

    %% Styles
    classDef datasource fill:#d1ecf1,stroke:#0c5460,stroke-width:2px,color:#0c5460;
    classDef integration fill:#d4edda,stroke:#155724,stroke-width:2px,color:#155724;
    classDef alertEngine fill:#f8d7da,stroke:#721c24,stroke-width:2px,color:#721c24;
    classDef pushGateway fill:#d1ecf1,stroke:#0c5460,stroke-width:2px,color:#0c5460;
    classDef centerService fill:#cce5ff,stroke:#004085,stroke-width:2px,color:#004085;
    classDef cliTools fill:#e2e3e5,stroke:#d6d8db,stroke-width:2px,color:#383d41;
    classDef edgeService fill:#fff3cd,stroke:#856404,stroke-width:2px,color:#856404;
    classDef support fill:#d6d8d9,stroke:#1b1e21,stroke-width:2px,color:#1b1e21;
    classDef caching fill:#fefefe,stroke:#6c757d,stroke-width:2px,color:#6c757d;
    classDef storage fill:#f5c6cb,stroke:#721c24,stroke-width:2px,color:#721c24;
```
