# pro-cms/phpnuxbill architecture

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

- Interactive diagram: https://gitdiagram.com/pro-cms/phpnuxbill
- Repository: https://github.com/pro-cms/phpnuxbill

## Overview

##### Project Type and Purpose
- PHPNuxBill is a full-stack, PHP-based ISP billing system integrating Mikrotik routers, FreeRadius, QR-code voucher generation, payment gateways, and notifications (SMS, WhatsApp, Telegram). It provides both admin and customer portals and supports plugins and multiple languages.

##### Key Directories & Architectural Patterns
- “system/”: Core MVC-like PHP application (bootloader, autoload, controllers, ORM).
- “ui/”: Presentation layer—TPL templates, JS/CSS assets, themes.
- “qrcode/”: Standalone QR-code library with caching.
- “admin/” & “pages_template/”: Installer and static page support.
- Configuration (“config.sample.php”), installer (“install/”), updater scripts.
- Cron jobs (“cron.php”, “cron_reminder.php”) for scheduled tasks (auto-renewal, reminders).
- Plugin extensibility (“system/plugin/”, “system/paymentgateway/”).
- Third-party PEAR2 libraries for Mikrotik API under “system/autoload/PEAR2/Net/RouterOS”.

##### Main Components
a. Web Clients
- Admin UI (browser → admin/index.php)
- Customer portal (browser → index.php)
b. Web Server & PHP Application
- Apache/Nginx + PHP 7.4+ interpreter
- Entry points (index.php, system/boot.php, system/api.php)
- Router/Dispatcher → Controllers → Models/ORM → Views (TPL in ui/ui/)
c. Core Services & Libraries
- ORM layer (system/orm.php) ↔ MySQL
- QRCode module (qrcode/) for voucher generation
- Mikrotik API client (PEAR2/Net/RouterOS) ↔ Mikrotik routers
- FreeRadius integration (SQL backend, radius scripts)
- Plugin and PaymentGateway managers (dynamic loading under system/plugin & system/paymentgateway)
- Notification services (SMS gateway via PHP-CURL, Telegram BOT API, WhatsApp API)
d. Scheduled Jobs
- Cron processes for auto-renewal, reminder emails/SMS
e. External Systems
- MySQL database
- Mikrotik devices
- FreeRadius server + radius SQL schema
- Payment provider endpoints (e.g., PayPal, bank APIs)
- SMS / WhatsApp / Telegram servers
f. Data & File Storage
- File uploads (system/uploads/)
- Caches (system/cache/, ui/cache/, qrcode/cache/)

##### Relationships & Data Flow
- Client → Web server (HTTP request)
- Web server → Router/Dispatcher → Controller → Model → DB ←→ ORM
- Controller → View → Client (HTML/JSON)
- Voucher generation request → QRCode lib → qrcode/cache → image output
- Controller calls Mikrotik API client → RouterOS devices (TCP)
- Controller writes to FreeRadius SQL tables → FreeRadius server
- Cron jobs → PHP scripts → DB and external services
- Notification modules → External APIs (SMS, Telegram, WhatsApp)
- Plugin manager dynamically loads plugin code and hooks into controllers/services
- Payment gateway modules ↔ External payment provider APIs

##### Architectural Patterns & Principles
- MVC-style separation: Controllers (system/controllers), Models (ORM + autoload classes), Views (ui/ui/*.tpl).
- Dependency injection via autoloader (system/autoload/).
- Plugin architecture: Hookers in autoload, plugin manager loads extensions.
- Layered design: Presentation (ui/), Business logic (controllers/services), Data access (ORM), Integration adapters (Mikrotik, Payment, Notification).
- Cron-based scheduled tasks separate from HTTP flow.

##### Essential Details to Capture
- Entry points: index.php → boot.php → dispatcher (controllers)
- Autoload mechanism loading classes under system/autoload/
- Core controller modules (e.g., order, voucher, customer, router)
- Dynamic plugin and payment-gateway loading
- QRCode module with cache layer
- Cron processes and their interactions with core services
- Notification subsystems

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Web Clients
    subgraph "Web Clients"
        direction TB
        AdminUI["Admin UI (admin/index.php)"]:::external
        CustomerUI["Customer Portal (index.php)"]:::external
    end

    %% Web Server & PHP App
    subgraph "Web Server + PHP App"
        direction TB
        WebServer["Apache/Nginx + PHP 7.4+"]:::internal

        subgraph "Entry Points"
            direction TB
            Boot["Bootloader & Dispatcher (system/boot.php)"]:::internal
            API["API Endpoint (system/api.php)"]:::internal
        end

        subgraph "Autoloader & Core Services"
            direction TB
            AppAutoload["App Autoloader (system/autoload/App.php)"]:::internal
            Hookers["Hookers (system/autoload/Hookers.php)"]:::internal
            RadiusAutoload["Radius Autoload (system/autoload/Radius.php)"]:::internal
            MikrotikAutoload["Mikrotik Autoload (system/autoload/Mikrotik.php)"]:::internal
            PEAR2Client["RouterOS Client (system/autoload/PEAR2/Net/RouterOS/Client.php)"]:::internal
        end

        subgraph "MVC Controllers"
            direction TB
            OrderCtrl["Order Controller (system/controllers/order.php)"]:::internal
            VoucherCtrl["Voucher Controller (system/controllers/voucher.php)"]:::internal
            RoutersCtrl["Routers Controller (system/controllers/routers.php)"]:::internal
            PaymentGatewayCtrl["PaymentGateway Controller (system/controllers/paymentgateway.php)"]:::internal
            PluginManagerCtrl["PluginManager Controller (system/controllers/pluginmanager.php)"]:::internal
            RadiusCtrl["Radius Controller (system/controllers/radius.php)"]:::internal
        end

        subgraph "Business Logic Services"
            direction TB
            ORM["ORM Layer (system/orm.php)"]:::internal
            QRCode["QRCode Module (qrcode/qrlib.php)"]:::internal
            PluginMgr["Plugin Manager (system/plugin/)"]:::internal
            PaymentMgr["PaymentGateway Manager (system/paymentgateway/)"]:::internal
            Notification["Notification Services"]:::internal
            MikrotikClient["Mikrotik API Client"]:::internal
            RadiusClient["FreeRadius Integration"]:::internal
        end

        subgraph "Views & Assets"
            direction TB
            Templates["TPL Templates (ui/ui/*.tpl)"]:::internal
            JSAssets["JS Assets (ui/lib/js/)"]:::internal
            CSSAssets["CSS Assets (ui/lib/css/)"]:::internal
            Themes["Themes (ui/themes/)"]:::internal
        end
    end

    %% Scheduled Jobs
    subgraph "Cron Jobs"
        direction TB
        CronAuto["Auto-renewal Cron (system/cron.php)"]:::cron
        CronRemind["Reminder Cron (system/cron_reminder.php)"]:::cron
    end

    %% Installer & Static Pages
    subgraph "Installer & Static Pages"
        direction TB
        Installer["Installer (install/index.php)"]:::internal
        Updater["Updater (install/update.php)"]:::internal
        Pages["Static Pages Template (pages_template/*.html)"]:::internal
    end

    %% Data & File Storage
    subgraph "Data & File Storage"
        direction TB
        MySQLDB["MySQL Database"]:::datastore
        FileUploads["File Uploads (system/uploads/)"]:::datastore
        CacheSys["System Cache (system/cache/)"]:::datastore
        CacheUI["UI Cache (ui/cache/)"]:::datastore
        QRCache["QRCode Cache (qrcode/cache/)"]:::datastore
        LangFiles["Language Files (system/lan/*.json)"]:::datastore
        ConfigSample["Config Sample (config.sample.php)"]:::datastore
        UpdatesMeta["Updates Metadata (system/updates.json)"]:::datastore
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        MikrotikDev["Mikrotik Devices"]:::external
        FreeRadiusSrv["FreeRadius Server"]:::external
        PaymentAPIs["Payment Provider APIs"]:::external
        SMSAPI["SMS/WhatsApp/Telegram APIs"]:::external
    end

    %% Relationships
    AdminUI -->|HTTP| WebServer
    CustomerUI -->|HTTP| WebServer

    WebServer --> Boot
    WebServer --> API

    Boot --> AppAutoload
    Boot --> Hookers
    AppAutoload --> Controllers
    Hookers --> PluginMgr

    API -->|Route| OrderCtrl
    API -->|Route| VoucherCtrl
    API -->|Route| RoutersCtrl
    API -->|Route| PaymentGatewayCtrl
    API -->|Route| PluginManagerCtrl
    API -->|Route| RadiusCtrl

    Controllers --> ORM
    Controllers --> QRCode
    Controllers --> MikrotikClient
    Controllers --> RadiusClient
    Controllers --> PluginMgr
    Controllers --> PaymentMgr
    Controllers --> Notification

    ORM --> MySQLDB
    RadiusClient --> MySQLDB
    QRCode --> QRCache
    PluginMgr -->|loads| system/plugin/
    PaymentMgr -->|loads| system/paymentgateway/
    Notification --> SMSAPI

    MikrotikClient -->|TCP| MikrotikDev
    RadiusClient -->|SQL| FreeRadiusSrv

    Controllers --> Templates
    Controllers --> JSAssets
    Controllers --> CSSAssets
    Controllers --> Themes

    CronAuto --> ORM
    CronAuto --> Notification
    CronRemind --> ORM
    CronRemind --> Notification

    Installer --> MySQLDB
    Updater --> UpdatesMeta
    Installer --> Pages

    FileUploads --> MySQLDB
    CacheSys --> Controllers
    CacheUI --> Templates
    QRCache --> QRCode
    LangFiles --> Controllers
    ConfigSample --> WebServer
    UpdatesMeta --> Updater

    %% Click Events
    click AdminUI "https://github.com/pro-cms/phpnuxbill/blob/master/admin/index.php"
    click CustomerUI "https://github.com/pro-cms/phpnuxbill/blob/master/index.php"
    click Boot "https://github.com/pro-cms/phpnuxbill/blob/master/system/boot.php"
    click API "https://github.com/pro-cms/phpnuxbill/blob/master/system/api.php"
    click AppAutoload "https://github.com/pro-cms/phpnuxbill/blob/master/system/autoload/App.php"
    click Hookers "https://github.com/pro-cms/phpnuxbill/blob/master/system/autoload/Hookers.php"
    click RadiusAutoload "https://github.com/pro-cms/phpnuxbill/blob/master/system/autoload/Radius.php"
    click MikrotikAutoload "https://github.com/pro-cms/phpnuxbill/blob/master/system/autoload/Mikrotik.php"
    click PEAR2Client "https://github.com/pro-cms/phpnuxbill/blob/master/system/autoload/PEAR2/Net/RouterOS/Client.php"
    click OrderCtrl "https://github.com/pro-cms/phpnuxbill/blob/master/system/controllers/order.php"
    click VoucherCtrl "https://github.com/pro-cms/phpnuxbill/blob/master/system/controllers/voucher.php"
    click RoutersCtrl "https://github.com/pro-cms/phpnuxbill/blob/master/system/controllers/routers.php"
    click PaymentGatewayCtrl "https://github.com/pro-cms/phpnuxbill/blob/master/system/controllers/paymentgateway.php"
    click PluginManagerCtrl "https://github.com/pro-cms/phpnuxbill/blob/master/system/controllers/pluginmanager.php"
    click RadiusCtrl "https://github.com/pro-cms/phpnuxbill/blob/master/system/controllers/radius.php"
    click ORM "https://github.com/pro-cms/phpnuxbill/blob/master/system/orm.php"
    click Templates "https://github.com/pro-cms/phpnuxbill/tree/master/ui/ui/"
    click JSAssets "https://github.com/pro-cms/phpnuxbill/tree/master/ui/lib/js/"
    click CSSAssets "https://github.com/pro-cms/phpnuxbill/tree/master/ui/lib/css/"
    click Themes "https://github.com/pro-cms/phpnuxbill/tree/master/ui/themes/"
    click QRCode "https://github.com/pro-cms/phpnuxbill/blob/master/qrcode/qrlib.php"
    click QRCache "https://github.com/pro-cms/phpnuxbill/tree/master/qrcode/cache/"
    click PluginMgr "https://github.com/pro-cms/phpnuxbill/tree/master/system/plugin/"
    click PaymentMgr "https://github.com/pro-cms/phpnuxbill/tree/master/system/paymentgateway/"
    click CronAuto "https://github.com/pro-cms/phpnuxbill/blob/master/system/cron.php"
    click CronRemind "https://github.com/pro-cms/phpnuxbill/blob/master/system/cron_reminder.php"
    click LangFiles "https://github.com/pro-cms/phpnuxbill/tree/master/system/lan/"
    click Installer "https://github.com/pro-cms/phpnuxbill/blob/master/install/index.php"
    click Updater "https://github.com/pro-cms/phpnuxbill/blob/master/install/update.php"
    click Pages "https://github.com/pro-cms/phpnuxbill/tree/master/pages_template/"
    click FileUploads "https://github.com/pro-cms/phpnuxbill/tree/master/system/uploads/"
    click CacheSys "https://github.com/pro-cms/phpnuxbill/tree/master/system/cache/"
    click CacheUI "https://github.com/pro-cms/phpnuxbill/tree/master/ui/cache/"
    click ConfigSample "https://github.com/pro-cms/phpnuxbill/blob/master/config.sample.php"
    click UpdatesMeta "https://github.com/pro-cms/phpnuxbill/blob/master/system/updates.json"

    %% Styles
    classDef internal fill:#bbdefb,stroke:#0d47a1,color:#0d47a1
    classDef external fill:#c8e6c9,stroke:#2e7d32,color:#2e7d32
    classDef datastore fill:#ffe0b2,stroke:#ef6c00,color:#e65100
    classDef cron fill:#f0f4c3,stroke:#827717,color:#827717
```
