# mia0x75/falcon-plus architecture

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

- Interactive diagram: https://gitdiagram.com/mia0x75/falcon-plus
- Repository: https://github.com/mia0x75/falcon-plus

## Overview

##### Main Components
– Agent: Responsible for collecting metric data from hosts.
– Aggregator: Aggregates and processes the collected metrics.
– Alarm: Evaluates rules to trigger alerts.
– API: Exposes RESTful endpoints to interact with the system (for example, for configuration and querying).
– Exporter: Provides additional metric collection and self-monitoring.
– Gateway: Acts as an entry point for data in/out.
– Graph: Handles the visualization (including RRD tool integration).
– HBS (Heartbeat Server): Maintains agent heartbeats.
– Judge: Implements rule evaluation logic.
– NoData: Special handling for missing metrics.
– Transfer & Updater: Handle data forwarding and module status update respectively.
- Common Infrastructure: Note that there are common libraries (such as common/model, common/utils, common/sdk) shared across modules.
- Configuration & External Resources: There are JSON config files under “config”, and deployment artifacts like Dockerfiles, docker-compose.yml, and scripts for MySQL schema setup indicate the system relies on external services:
– MySQL: The primary database for storing configuration, metric history, and metadata.
– Redis: Used for caching and queuing in some modules (e.g., alarm, judge).

##### Relationships and Interactions
- Data Flow: Typically, Agent modules collect raw metric data from hosts and push them to Aggregator. From Aggregator, the processed metrics may be stored, forwarded to Graph, or trigger alerts through Alarm and Judge modules.
- API Exposure: The API module exposes endpoints for configuration, query, and control, likely interacting with the same database resource and caching modules.
- Control Flow: The system includes command-line commands (start, stop, check, monitor, reload) to manage each module. These commands form an operational layer that ties the modules together.
- Communication Protocols: There are indicators of RPC and possibly HTTP based on files in modules like “rpc”, “http” directories, as well as client SDK libraries in “common/sdk/requests”.

##### Important Architectural Patterns and Design Principles
- Modular / Microservice Architecture: Although packaged together, each module has its own lifecycle and business logic, usually communicating through well-defined APIs (HTTP, RPC) or shared caches.
- Separation of Concerns: Different modules are responsible for discrete parts of the monitoring solution (data collection, aggregation, alerting, visualization).
- Shared Libraries: There is a common package structure that indicates code reuse across modules.
- Deployment and Configuration Independence: Configuration files are centralized under the “config” directory, and deployment scripts (Docker, systemd, Vagrant) are provided for a consistent deployment environment.

##### Relevant Technologies and Frameworks
- Programming Language: Go (leveraging modules with go.mod and go.sum)
- Databases: MySQL for persistent storage; Redis for caching/queueing.
- Logging Frameworks: Logrus is used for logging (per enhancements in README).
- External Tools: Docker and docker-compose for containerized deployments; systemd and Vagrant for environment setup.
- Build Tools: Makefile, Dockerfiles for module packaging.

- Each major module (agent, aggregator, alarm, API, exporter, gateway, graph, hbs, judge, nodata, transfer, updater) should be represented as distinct components using clear labels.
- With key technologies (Go for services, MySQL and Redis for data storage, Docker for containerization, etc.) where applicable.
- Optionally, illustrate the shared “common” library layer to show code reuse and inter-module dependencies.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Collection Layer"
        A["Agent (Collect Metrics)"]:::core
        E["Exporter (Self-Monitoring)"]:::core
    end

    subgraph "Processing & Aggregation Layer"
        AG["Aggregator (Metrics Aggregation)"]:::core
        AL["Alarm (Alert Evaluation)"]:::core
        J["Judge (Rule Evaluation)"]:::core
        ND["NoData (Missing Metrics Handler)"]:::core
        T["Transfer (Data Forwarding)"]:::core
        U["Updater (Module Status Update)"]:::core
    end

    subgraph "Interface & Visualization Layer"
        API["API (RESTful Endpoints)"]:::core
        G["Gateway (Data In/Out)"]:::core
        GR["Graph (Visualization)"]:::core
        H["HBS (Heartbeat Server)"]:::core
    end

    subgraph "Supporting Infrastructure"
        C["Common Infrastructure (Shared Libraries)"]:::common
        CFG["Configuration Files"]:::config
        SQL["MySQL (Database)"]:::external
        RED["Redis (Cache/Queue)"]:::external
    end

    subgraph "Deployment Artifacts"
        DF["Dockerfile"]:::deploy
        DC["docker-compose.yml"]:::deploy
        SYS["scripts/systemd"]:::deploy
        MS["scripts/mysql"]:::deploy
    end

    %% Data Flow Connections
    A -->|"sends_metrics"| AG
    E -->|"pushes_metrics"| AG
    A -->|"sends_heartbeat"| H

    AG -->|"aggregates_to"| GR
    AG -->|"triggers"| AL
    AG -->|"feeds"| J
    AG -->|"forwards"| T
    AG -->|"updates"| U

    AL -->|"notifies"| API
    J -->|"notifies"| API

    G -->|"routes_to"| AG

    API -->|"rw_DB"| SQL
    API -->|"caches"| RED

    %% Shared Infrastructure Connections
    C ---|"shared_libs"| A
    C ---|"shared_libs"| E
    C ---|"shared_libs"| AG
    C ---|"shared_libs"| AL
    C ---|"shared_libs"| J
    C ---|"shared_libs"| ND
    C ---|"shared_libs"| T
    C ---|"shared_libs"| U
    C ---|"shared_libs"| API
    C ---|"shared_libs"| G
    C ---|"shared_libs"| GR
    C ---|"shared_libs"| H

    CFG ---|"provides_settings"| A
    CFG ---|"provides_settings"| E
    CFG ---|"provides_settings"| AG
    CFG ---|"provides_settings"| AL
    CFG ---|"provides_settings"| J
    CFG ---|"provides_settings"| ND
    CFG ---|"provides_settings"| T
    CFG ---|"provides_settings"| U
    CFG ---|"provides_settings"| API
    CFG ---|"provides_settings"| G
    CFG ---|"provides_settings"| GR
    CFG ---|"provides_settings"| H

    DF ---|"deployment"| API
    DF ---|"deployment"| A
    DF ---|"deployment"| AG
    DF ---|"deployment"| AL
    DF ---|"deployment"| E
    DF ---|"deployment"| G
    DF ---|"deployment"| GR
    DF ---|"deployment"| H
    DF ---|"deployment"| J
    DF ---|"deployment"| ND
    DF ---|"deployment"| T
    DF ---|"deployment"| U

    DC ---|"deployment"| API
    DC ---|"deployment"| A
    DC ---|"deployment"| AG
    DC ---|"deployment"| AL
    DC ---|"deployment"| E
    DC ---|"deployment"| G
    DC ---|"deployment"| GR
    DC ---|"deployment"| H
    DC ---|"deployment"| J
    DC ---|"deployment"| ND
    DC ---|"deployment"| T
    DC ---|"deployment"| U

    SYS ---|"deployment"| API
    SYS ---|"deployment"| A
    SYS ---|"deployment"| AG
    SYS ---|"deployment"| AL
    SYS ---|"deployment"| E
    SYS ---|"deployment"| G
    SYS ---|"deployment"| GR
    SYS ---|"deployment"| H
    SYS ---|"deployment"| J
    SYS ---|"deployment"| ND
    SYS ---|"deployment"| T
    SYS ---|"deployment"| U

    MS ---|"deployment"| API
    MS ---|"deployment"| A
    MS ---|"deployment"| AG
    MS ---|"deployment"| AL
    MS ---|"deployment"| E
    MS ---|"deployment"| G
    MS ---|"deployment"| GR
    MS ---|"deployment"| H
    MS ---|"deployment"| J
    MS ---|"deployment"| ND
    MS ---|"deployment"| T
    MS ---|"deployment"| U

    %% Click Events
    click A "https://github.com/mia0x75/falcon-plus/tree/master/modules/agent"
    click AG "https://github.com/mia0x75/falcon-plus/tree/master/modules/aggregator"
    click AL "https://github.com/mia0x75/falcon-plus/tree/master/modules/alarm"
    click API "https://github.com/mia0x75/falcon-plus/tree/master/modules/api"
    click E "https://github.com/mia0x75/falcon-plus/tree/master/modules/exporter"
    click G "https://github.com/mia0x75/falcon-plus/tree/master/modules/gateway"
    click GR "https://github.com/mia0x75/falcon-plus/tree/master/modules/graph"
    click H "https://github.com/mia0x75/falcon-plus/tree/master/modules/hbs"
    click J "https://github.com/mia0x75/falcon-plus/tree/master/modules/judge"
    click ND "https://github.com/mia0x75/falcon-plus/tree/master/modules/nodata"
    click T "https://github.com/mia0x75/falcon-plus/tree/master/modules/transfer"
    click U "https://github.com/mia0x75/falcon-plus/tree/master/modules/updater"
    click C "https://github.com/mia0x75/falcon-plus/tree/master/common"
    click CFG "https://github.com/mia0x75/falcon-plus/tree/master/config"
    click DF "https://github.com/mia0x75/falcon-plus/tree/master/Dockerfile"
    click DC "https://github.com/mia0x75/falcon-plus/blob/master/docker-compose.yml"
    click SYS "https://github.com/mia0x75/falcon-plus/tree/master/scripts/systemd"
    click MS "https://github.com/mia0x75/falcon-plus/tree/master/scripts/mysql"

    %% Styling
    classDef core fill:#BBDEFB,stroke:#0d47a1,stroke-width:2px;
    classDef common fill:#FFF9C4,stroke:#F57F17,stroke-width:2px;
    classDef config fill:#C8E6C9,stroke:#388E3C,stroke-width:2px;
    classDef external fill:#FFCDD2,stroke:#C62828,stroke-width:2px;
    classDef deploy fill:#D1C4E9,stroke:#512DA8,stroke-width:2px;
```
