# jokob-sk/netalertx architecture

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

- Interactive diagram: https://gitdiagram.com/jokob-sk/netalertx
- Repository: https://github.com/jokob-sk/netalertx

## Overview

##### Project type and purpose
- NetAlertX is a full-stack, containerized network-scanning and alert system. It provides:
- A web UI (PHP + JavaScript) served by Nginx + PHP-FPM
- A Python-based API layer (REST, GraphQL)
- A scheduler/worker subsystem for scans and workflows
- A plugin framework for scanners and notification gateways
- A SQLite data store for configuration and events

##### Top-level structure & architectural patterns
- Directories of note:
- front/ → PHP code, UI templates, JS/CSS assets, plugin scripts
- server/ → Python API server, DB abstractions, scheduler, workflows, messaging
- back/ + cron_script.sh → legacy cron wrapper
- config/, db/ → runtime volumes (host-mounted in Docker)
- Dockerfile + docker-compose.yml → multi-service container orchestration
- Pattern: Monolithic container running multiple “services”
(Nginx, PHP-FPM, Cron, Python server)
- Plugin-based modularity: script files in front/plugins and server/plugin_utils

##### Core components & interactions
a. Web UI layer
- Nginx proxy / static assets → routes PHP requests to PHP-FPM
- PHP-FPM executes front/*.php → renders pages + calls plugin scripts
- PHP → may proxy AJAX/GraphQL calls to Python API (port configurable)
b. API layer (Python)
- Exposes endpoints: REST (api_server/*) and GraphQL
- Handles business logic: device scanning, heuristics, session/events
- Orchestrates workflows, scheduling, plugin invocation
- Persists & queries SQLite DB via server/database.py
c. Scheduler & workers
- Cron jobs (back/cron_script.sh or container crond) invoke scan scripts
- Python scheduler (server/scheduler.py) dispatches scan tasks & workflows
- Plugin scripts (front/plugins/**/script.py) implement scanners & notifications
d. Data layer
- SQLite database (db/app.db) for devices, events, config, workflows
- Versioned via SQL upgrade scripts (server/db/db_upgrade.py)
e. Plugin & notification framework
- Plugins live under front/plugins (scanner & notification handlers)
- Python server loads plugin metadata (server/plugin.py)
- Notifications via apprise or native Python modules (server/messaging)
f. Container orchestration
- Dockerfile builds a single image with Nginx, PHP, Python, Cron
- docker-compose.yml orchestrates service startup, volume mounts, networks
- .devcontainer for local VSCode development

##### Architectural patterns & design principles
- Separation of concerns:
- Presentation (PHP UI) vs Business (Python API) vs Data (SQLite)
- Plugin abstraction for scanners & gateways
- Layered architecture:
- Client ⇄ UI ⇄ API ⇄ DB
- Scheduler / Cron orthogonal to request flow
- Extensibility: all plugins follow a directory + config.json + script.py template

##### Essential detail checklist
- Four runtime services in the container
- Scheduling vs request-driven flows separately
- Plugin directories & config.json files as extension points
- External notification/integration services

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Browser["Browser"]:::presentation

    %% Container Services
    subgraph "NetAlertX Container"
        direction TB
        Nginx["Nginx"]:::presentation
        PHPFPM["PHP-FPM (front/)"]:::presentation
        PythonAPI["Python API (server/)<br/>PORT=20211"]:::backend
        Cron["Cron"]:::backend
        Scheduler["Python Scheduler<br/>(server/scheduler.py)"]:::backend
    end

    %% Data Layer
    DB["SQLite Database<br/>(db/app.db)"]:::data

    %% Plugin Framework
    frontPlugins["front/plugins"]:::plugin
    serverPlugins["server/plugin_utils"]:::plugin

    %% External Integrations
    ExtServices["External Notification Services"]:::external

    %% Volume Mounts
    ConfigVol["host/config ↔ /app/config"]:::volume
    DBVol["host/db ↔ /app/db"]:::volume
    APITmp["tmpfs ↔ /app/api"]:::volume

    %% Flows
    Browser -->|HTTP| Nginx
    Nginx -->|fastcgi_pass| PHPFPM
    PHPFPM -->|reads/writes| DB
    PHPFPM -->|HTTP API calls| PythonAPI
    PHPFPM -->|loads plugins| frontPlugins

    PythonAPI -->|queries| DB
    PythonAPI -->|invokes plugins| serverPlugins
    PythonAPI -->|sends notifications| ExtServices

    Cron -->|shell invocation| Scheduler
    Scheduler -->|reads/writes| DB
    Scheduler -->|executes scripts| serverPlugins

    %% Volume connections
    ConfigVol --- PHPFPM
    ConfigVol --- PythonAPI
    DBVol --- DB
    APITmp --- PythonAPI

    %% Click Events - Frontend
    click frontPlugins "https://github.com/jokob-sk/netalertx/tree/main/front/plugins/"
    click PHPFPM "https://github.com/jokob-sk/netalertx/blob/main/front/index.php"
    click PHPFPM "https://github.com/jokob-sk/netalertx/blob/main/front/*.php"
    click PHPFPM "https://github.com/jokob-sk/netalertx/tree/main/front/css/"
    click PHPFPM "https://github.com/jokob-sk/netalertx/tree/main/front/js/"
    click PHPFPM "https://github.com/jokob-sk/netalertx/tree/main/front/php/templates/"
    click frontPluginsCore "https://github.com/jokob-sk/netalertx/blob/main/front/pluginsCore.php"
    click frontTemplateDir "https://github.com/jokob-sk/netalertx/tree/main/front/plugins/__template/"

    %% Click Events - Backend API
    click PythonAPI "https://github.com/jokob-sk/netalertx/blob/main/server/api.py"
    click PythonAPI "https://github.com/jokob-sk/netalertx/tree/main/server/api_server/"
    click PythonAPI "https://github.com/jokob-sk/netalertx/blob/main/server/database.py"
    click PythonAPI "https://github.com/jokob-sk/netalertx/blob/main/server/crypto_utils.py"
    click PythonAPI "https://github.com/jokob-sk/netalertx/tree/main/server/models/"

    %% Click Events - Scheduler & Workers
    click Cron "https://github.com/jokob-sk/netalertx/blob/main/back/cron_script.sh"
    click Scheduler "https://github.com/jokob-sk/netalertx/blob/main/server/scheduler.py"
    click Scheduler "https://github.com/jokob-sk/netalertx/tree/main/server/scan/"
    click Scheduler "https://github.com/jokob-sk/netalertx/tree/main/server/workflows/"

    %% Click Events - Plugin & Notification Framework
    click serverPlugins "https://github.com/jokob-sk/netalertx/blob/main/server/plugin.py"
    click serverPlugins "https://github.com/jokob-sk/netalertx/blob/main/server/plugin_utils.py"
    click serverPlugins "https://github.com/jokob-sk/netalertx/tree/main/server/messaging/"

    %% Click Events - Data Layer
    click DB "https://github.com/jokob-sk/netalertx/tree/main/db/"
    click DB "https://github.com/jokob-sk/netalertx/blob/main/back/app.db"
    click DB "https://github.com/jokob-sk/netalertx/blob/main/server/db/db_upgrade.py"
    click DB "https://github.com/jokob-sk/netalertx/blob/main/server/db/db_helper.py"

    %% Click Events - Container Orchestration
    click Dockerfile "https://github.com/jokob-sk/netalertx/tree/main/Dockerfile"
    click Dockerfile "https://github.com/jokob-sk/netalertx/blob/main/docker-compose.yml"
    click Dockerfile "https://github.com/jokob-sk/netalertx/tree/main/.devcontainer/"

    %% Styles
    classDef presentation fill:#b2f7b2,stroke:#2d5f2d,color:#000
    classDef backend fill:#b2d4f0,stroke:#2a4d69,color:#000
    classDef data fill:#f7f1b2,stroke:#8c7c1f,color:#000
    classDef plugin fill:#e0b3f0,stroke:#5f2d69,color:#000
    classDef external fill:#f0b38c,stroke:#80630f,color:#000
    classDef volume fill:#cccccc,stroke:#888888,color:#000
```
