# openwisp/openwisp-monitoring architecture

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

- Interactive diagram: https://gitdiagram.com/openwisp/openwisp-monitoring
- Repository: https://github.com/openwisp/openwisp-monitoring

## Overview

##### Main Components
a. User Interface Layer:
- Django Admin, dashboard templates, and static assets (JS, CSS, images).
- Client-side monitoring charts, maps, and configuration screens.
b. API Layer:
- REST endpoints provided under “device/api” and “monitoring/api” for external integrations.
c. Application / Business Logic Layer:
- The “check” module: Contains classes (ping, iperf3, wifi_clients, etc.) that manage network checks, scheduling (via management commands and tasks), and alerting.
- The “device” module: Manages network devices, including configuration, health status, and device-specific checks.
- The “monitoring” module: Coordinates overall monitoring logic, configurations, metrics aggregation, and visualization.
d. Data Storage:
- The Django relational database (PostgreSQL, MySQL, etc.) to persist models and configurations.
- The InfluxDB backend under “db/backends/influxdb”: Handles time-series data storage for metrics.
e. Deployment and Integration Components:
- Docker and docker-compose files indicating containerized deployment.
- CI/CD configurations under “.github/workflows” to automate testing and deployment.

##### Relationships and Interactions
- Within the core business layer, show interactions between the check, device, and monitoring apps. For instance, the check service executes network tests and generates metrics that the monitoring module aggregates and presents.
- Communication between the business logic layer and the data storage components:

##### Architectural Patterns and Principles
- Modular structure inherent in Django projects. Each Django “app” (check, device, monitoring) is relatively self-contained, yet they interact to form the full monitoring solution.
- That the project follows a separation of concerns – the UI layer (templates/static files) is distinct from the business logic (services, management commands, task scheduling) and data access layers (ORM and InfluxDB clients).
- For scheduling and check execution, show that management commands (e.g., run_checks) and asynchronous tasks are part of the application’s workflow.

##### Relevant Technologies
- Python and Django as the core framework.
- InfluxDB as the time-series database (via the custom backend in “db/backends/influxdb”).
- Docker (Dockerfile, docker-compose) for deployment and containerization.
- Various front-end libraries and utilities for dashboard rendering (visible in the device and monitoring static directories).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface"
        UI_Admin1["Django Admin (Device)"]:::ui
        UI_Admin2["Django Admin (Monitoring)"]:::ui
        UI_Static1["Static Assets (Device)"]:::ui
        UI_Static2["Static Assets (Monitoring)"]:::ui
    end

    %% API Layer
    subgraph "API Layer"
        API_Device_URLs["Device API (urls.py)"]:::api
        API_Device_Views["Device API (views.py)"]:::api
        API_Device_Filters["Device API (filters.py)"]:::api
        API_Device_Serializers["Device API (serializers.py)"]:::api
        API_Monitoring_URLs["Monitoring API (urls.py)"]:::api
        API_Monitoring_Views["Monitoring API (views.py)"]:::api
    end

    %% Application / Business Logic Layer
    subgraph "Business Logic / Apps"
        %% Check Module
        subgraph "Check Module"
            Check_Core["Check Core (checks.py)"]:::logic
            Check_Ping["Ping Check (ping.py)"]:::logic
            Check_Iperf3["Iperf3 Check (iperf3.py)"]:::logic
            Check_Wifi["WiFi Clients Check (wifi_clients.py)"]:::logic
            Check_Management["Management Command (run_checks.py)"]:::logic
            Check_Tasks["Tasks (tasks.py)"]:::logic
        end
        %% Device Module
        subgraph "Device Module"
            Device_Core["Device Core (models.py)"]:::logic
            Device_Admin["Device Admin (admin.py)"]:::logic
            Device_Sub["Base Models (base/models.py)"]:::logic
            Device_Tasks["Tasks (tasks.py)"]:::logic
        end
        %% Monitoring Module
        subgraph "Monitoring Module"
            Monitoring_Core["Monitoring Core (models.py)"]:::logic
            Monitoring_Config["Configuration (configuration.py)"]:::logic
            Monitoring_Tasks["Tasks (tasks.py)"]:::logic
            Monitoring_Management["Management Command (migrate_timeseries.py)"]:::logic
        end
    end

    %% Data Storage
    subgraph "Data Storage"
        DB_Relational["Relational Database (Models)"]:::storage
        InfluxDB_Backend["InfluxDB Time-Series DB"]:::storage
    end

    %% Deployment and Integration
    subgraph "Deployment & Integration"
        Docker["Docker (Dockerfile & docker-compose.yml)"]:::deploy
        CICD["CI/CD Configurations"]:::deploy
    end

    %% Connections: UI and API layers triggering Business Logic
    UI_Admin1 -- "triggers" --> Check_Core
    UI_Admin1 -- "triggers" --> Device_Core
    UI_Admin1 -- "triggers" --> Monitoring_Core

    UI_Admin2 -- "triggers" --> Check_Core
    UI_Admin2 -- "triggers" --> Device_Core
    UI_Admin2 -- "triggers" --> Monitoring_Core

    UI_Static1 -- "provides assets to" --> Check_Core
    UI_Static2 -- "provides assets to" --> Monitoring_Core

    API_Device_URLs -- "REST call" --> Device_Core
    API_Device_Views -- "REST call" --> Device_Core
    API_Device_Filters -- "filters data" --> Device_Core
    API_Device_Serializers -- "serializes data" --> Device_Core

    API_Monitoring_URLs -- "REST call" --> Monitoring_Core
    API_Monitoring_Views -- "REST call" --> Monitoring_Core

    %% Internal Business Logic interactions within Check Module
    Check_Core -- "executes" --> Check_Ping
    Check_Core -- "executes" --> Check_Iperf3
    Check_Core -- "executes" --> Check_Wifi
    Check_Core -- "schedules" --> Check_Management
    Check_Core -- "triggers" --> Check_Tasks

    %% Internal Business Logic interactions within Device Module
    Device_Core -- "manages" --> Device_Admin
    Device_Core -- "associates with" --> Device_Sub
    Device_Core -- "triggers" --> Device_Tasks

    %% Internal Business Logic interactions within Monitoring Module
    Monitoring_Core -- "aggregates using" --> Monitoring_Config
    Monitoring_Core -- "triggers" --> Monitoring_Tasks
    Monitoring_Core -- "invokes" --> Monitoring_Management

    %% Business Logic to Data Storage interactions
    Check_Core -- "stores config in" --> DB_Relational
    Device_Core -- "stores device data in" --> DB_Relational
    Monitoring_Core -- "stores monitoring data in" --> DB_Relational

    Check_Tasks -- "writes metrics to" --> InfluxDB_Backend
    Monitoring_Tasks -- "writes metrics to" --> InfluxDB_Backend

    %% Deployment and Integration connections
    Docker -- "deploys" --> UI_Admin1
    Docker -- "deploys" --> API_Device_URLs
    Docker -- "deploys" --> Check_Core

    CICD -- "automates builds for" --> Docker

    %% Click Events for User Interface Layer
    click UI_Admin1 "https://github.com/openwisp/openwisp-monitoring/blob/master/openwisp_monitoring/device/templates/admin/dashboard/device_map.html"
    click UI_Admin2 "https://github.com/openwisp/openwisp-monitoring/blob/master/openwisp_monitoring/monitoring/templates/admin/chart_inline.html"
    click UI_Static1 "https://github.com/openwisp/openwisp-monitoring/tree/master/openwisp_monitoring/device/static/monitoring"
    click UI_Static2 "https://github.com/openwisp/openwisp-monitoring/tree/master/openwisp_monitoring/monitoring/static/monitoring"

    %% Click Events for API Layer
    click API_Device_URLs "https://github.com/openwisp/openwisp-monitoring/blob/master/openwisp_monitoring/device/api/urls.py"
    click API_Device_Views "https://github.com/openwisp/openwisp-monitoring/blob/master/openwisp_monitoring/device/api/views.py"
    click API_Device_Filters "https://github.com/openwisp/openwisp-monitoring/blob/master/openwisp_monitoring/device/api/filters.py"
    click API_Device_Serializers "https://github.com/openwisp/openwisp-monitoring/blob/master/openwisp_monitoring/device/api/serializers.py"
    click API_Monitoring_URLs "https://github.com/openwisp/openwisp-monitoring/blob/master/openwisp_monitoring/monitoring/api/urls.py"
    click API_Monitoring_Views "https://github.com/openwisp/openwisp-monitoring/blob/master/openwisp_monitoring/monitoring/api/views.py"

    %% Click Events for Check Module in Business Logic
    click Check_Core "https://github.com/openwisp/openwisp-monitoring/blob/master/openwisp_monitoring/check/checks.py"
    click Check_Ping "https://github.com/openwisp/openwisp-monitoring/blob/master/openwisp_monitoring/check/classes/ping.py"
    click Check_Iperf3 "https://github.com/openwisp/openwisp-monitoring/blob/master/openwisp_monitoring/check/classes/iperf3.py"
    click Check_Wifi "https://github.com/openwisp/openwisp-monitoring/blob/master/openwisp_monitoring/check/classes/wifi_clients.py"
    click Check_Management "https://github.com/openwisp/openwisp-monitoring/blob/master/openwisp_monitoring/check/management/commands/run_checks.py"
    click Check_Tasks "https://github.com/openwisp/openwisp-monitoring/blob/master/openwisp_monitoring/check/tasks.py"

    %% Click Events for Device Module in Business Logic
    click Device_Core "https://github.com/openwisp/openwisp-monitoring/blob/master/openwisp_monitoring/device/models.py"
    click Device_Admin "https://github.com/openwisp/openwisp-monitoring/blob/master/openwisp_monitoring/device/admin.py"
    click Device_Sub "https://github.com/openwisp/openwisp-monitoring/blob/master/openwisp_monitoring/device/base/models.py"
    click Device_Tasks "https://github.com/openwisp/openwisp-monitoring/blob/master/openwisp_monitoring/device/tasks.py"

    %% Click Events for Monitoring Module in Business Logic
    click Monitoring_Core "https://github.com/openwisp/openwisp-monitoring/blob/master/openwisp_monitoring/monitoring/models.py"
    click Monitoring_Config "https://github.com/openwisp/openwisp-monitoring/blob/master/openwisp_monitoring/monitoring/configuration.py"
    click Monitoring_Tasks "https://github.com/openwisp/openwisp-monitoring/blob/master/openwisp_monitoring/monitoring/tasks.py"
    click Monitoring_Management "https://github.com/openwisp/openwisp-monitoring/blob/master/openwisp_monitoring/monitoring/management/commands/migrate_timeseries.py"

    %% Click Events for Data Storage
    click DB_Relational "https://github.com/openwisp/openwisp-monitoring/blob/master/openwisp_monitoring/check/models.py"
    click DB_Relational "https://github.com/openwisp/openwisp-monitoring/blob/master/openwisp_monitoring/device/models.py"
    click DB_Relational "https://github.com/openwisp/openwisp-monitoring/blob/master/openwisp_monitoring/monitoring/models.py"
    click InfluxDB_Backend "https://github.com/openwisp/openwisp-monitoring/blob/master/openwisp_monitoring/db/backends/influxdb/client.py"
    click InfluxDB_Backend "https://github.com/openwisp/openwisp-monitoring/blob/master/openwisp_monitoring/db/backends/influxdb/queries.py"

    %% Click Events for Deployment & Integration
    click Docker "https://github.com/openwisp/openwisp-monitoring/tree/master/Dockerfile"
    click Docker "https://github.com/openwisp/openwisp-monitoring/blob/master/docker-compose.yml"
    click CICD "https://github.com/openwisp/openwisp-monitoring/blob/master/ .github/workflows/ci.yml"
    click CICD "https://github.com/openwisp/openwisp-monitoring/blob/master/ .github/workflows/pypi.yml"
    click CICD "https://github.com/openwisp/openwisp-monitoring/blob/master/ .github/workflows/version-branch.yml"

    %% Styles
    classDef ui fill:#f9e79f,stroke:#6c3483,stroke-width:2px;
    classDef api fill:#aed6f1,stroke:#2471a3,stroke-width:2px;
    classDef logic fill:#a9dfbf,stroke:#117864,stroke-width:2px;
    classDef storage fill:#f9c5d1,stroke:#922b21,stroke-width:2px;
    classDef deploy fill:#fadbd8,stroke:#943126,stroke-width:2px;
```
