How jokob-sk/netalertx works
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