# nginx/agent architecture

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

- Interactive diagram: https://gitdiagram.com/nginx/agent
- Repository: https://github.com/nginx/agent

## Overview

##### Project Type and Purpose
- This is a Go-based agent application designed to remotely manage and monitor NGINX instances.
- Its core responsibilities include remotely configuring NGINX servers and collecting/aggregating real-time performance metrics.
- The README emphasizes “Remote management” and “Real-time metrics,” while the file structure shows many directories for core logic (src/core), plugin/extension systems (src/plugins, src/extensions), and SDK components (sdk/).

##### Key Architectural Components Identified
a. Core Agent:
– Represented by main.go and the “src/core” package. This is the main entry point and includes:
- Configuration management (src/core/config)
- Metrics collection, processing, and aggregation (src/core/metrics)
- Communication services (gRPC setups, network modules in src/core)
- Plugin integrations and extensibility (src/plugins)
b. SDK Layer:
– Found in the “sdk” directory. This provides:
- Common libraries and helpers for configuration, events (sdk/agent/events), and gRPC communication (sdk/grpc).
- Abstractions for external integrations and interfacing with NGINX via defined proto APIs.
c. Extensions and Plugins:
– Located under “src/extensions” and “src/plugins”.
– These components implement advanced functionalities like:
- Advanced metrics aggregation and ingestion (advanced-metrics)
- NGINX App Protect monitoring and threat analysis
- Prometheus metrics exporter integration
- Other domain-specific functionalities (e.g., PHP-FPM metrics, additional system monitoring modules)
d. Packaging, Deployment, and CI/CD:
– Files such as several Makefiles, .nfpm.yaml, container packaging scripts, and GitHub workflows indicate a structured build and CI/CD process.
– There is also dedicated documentation (docs folder) and sample deployment configurations (examples folder).

##### Interactions and Data Flow
- The agent (core component) interacts with:
– Local NGINX instances, by reading configuration files (e.g., nginx-agent.conf) and logs.
– External systems such as remote management platforms (F5 or NGINX One Trial) using gRPC and RESTful APIs.
– Collects metrics (logs, system statistics) which are processed by the Metrics Collector modules.
– Loads plugins/extensions to further process incoming data or to add management capabilities.
- The SDK layer serves as an interface between the core agent and external communication targets, packaging messaging protocols and event streams.
- Extensions enhance the core functionality by implementing specialized collectors, aggregators, or processors – forming a plug-and-play subsystem.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Interfaces"
        NGINXInstances["NGINX Instances"]:::external
        RemoteMgmt["Remote Management Systems"]:::external
        MetricsDashboard["Metrics Dashboard (Prometheus/Grafana)"]:::external
    end

    subgraph "Agent Core"
        Engine["Core Agent Engine"]:::core
        ConfigMgr["Configuration Management"]:::sub
        MetricsAgg["Metrics Collection & Aggregation"]:::sub
        GRPC["gRPC Services"]:::sub
        Network["Network Services"]:::sub
    end

    subgraph "SDK & Communication Layer"
        SDK["SDK & Communication Layer"]:::sdk
    end

    subgraph "Plugin & Extension Systems"
        PluginSys["Plugin System"]:::plugin
        ExtModules["Extension Modules"]:::plugin
    end

    subgraph "Packaging & Deployment"
        Pack_Makefile["Makefile (packaging)"]:::pack
        Pack_nfpm[".nfpm.yaml"]:::pack
        Pack_scripts["Scripts (packages)"]:::pack
        Pack_docs["Documentation (docs)"]:::pack
        Pack_examples["Examples"]:::pack
    end

    %% External Interfaces to Agent Core
    RemoteMgmt -->|"command"| ConfigMgr
    NGINXInstances -->|"metrics"| MetricsAgg
    MetricsAgg -->|"report"| MetricsDashboard

    %% Internal core interactions
    Engine --> ConfigMgr
    Engine --> MetricsAgg
    Engine --> GRPC
    Engine --> Network

    %% Core to other internal systems
    Engine --> SDK
    Engine --> PluginSys
    Engine --> ExtModules

    %% Packaging triggers deployment of the Agent
    Pack_Makefile -->|"build"| Engine

    %% Click Events
    click Engine "https://github.com/nginx/agent/tree/main/src/core/"
    click ConfigMgr "https://github.com/nginx/agent/tree/main/src/core/config/"
    click MetricsAgg "https://github.com/nginx/agent/tree/main/src/core/metrics/"
    click GRPC "https://github.com/nginx/agent/blob/main/src/core/grpc.go"
    click Network "https://github.com/nginx/agent/tree/main/src/core/network/"
    click PluginSys "https://github.com/nginx/agent/tree/main/src/plugins/"
    click ExtModules "https://github.com/nginx/agent/tree/main/src/extensions/"
    click SDK "https://github.com/nginx/agent/tree/main/sdk/"
    click Pack_Makefile "https://github.com/nginx/agent/blob/main/Makefile.packaging"
    click Pack_nfpm "https://github.com/nginx/agent/blob/main/.nfpm.yaml"
    click Pack_scripts "https://github.com/nginx/agent/tree/main/scripts/packages/"
    click Pack_docs "https://github.com/nginx/agent/tree/main/docs/"
    click Pack_examples "https://github.com/nginx/agent/tree/main/examples/"

    %% Styles
    classDef core fill:#FFECB3,stroke:#333,stroke-width:2px;
    classDef sub fill:#FFF176,stroke:#333,stroke-width:2px;
    classDef sdk fill:#A5D6A7,stroke:#333,stroke-width:2px;
    classDef plugin fill:#81D4FA,stroke:#333,stroke-width:2px;
    classDef pack fill:#EF9A9A,stroke:#333,stroke-width:2px;
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5;
```
