Skip to content

PyroRadius — Project Overview

Version: 1.0 (Documentation) Last Updated: 2026-07-13 Organization: PyroNet Solutions, Lahore, Pakistan Application URL: https://your-server-ip (production VPS)

Table of Contents

  1. What is PyroRadius?
  2. Business Context
  3. Who It's For
  4. Key Features
  5. Technology Stack Summary
  6. Deployment Information
  7. Version History
  8. Key Contacts

What is PyroRadius?

PyroRadius is a full-stack ISP (Internet Service Provider) billing and RADIUS management platform built exclusively for Indus Broadband, operating under PyroNet Solutions in Lahore, Pakistan. It consolidates every operational function of a modern ISP — customer lifecycle management, automated billing, network access control via RADIUS, MikroTik router integration, OLT/FTTH management, WhatsApp-based customer communication, field engineer dispatch, TR-069 device provisioning, and executive-level reporting — into a single, role-aware web application.

PyroRadius replaces fragmented spreadsheets, standalone RADIUS servers, and disconnected billing tools with a unified platform where every action is audited, every permission is scoped, and every network event is traceable back to a customer record.

The system name reflects its dual purpose: Pyro (from PyroNet Solutions) + RADIUS (the authentication protocol at the heart of PPPoE broadband access control).

Business Context

PyroNet Solutions operates as an ISP and IT services company in Lahore, Pakistan, providing broadband connectivity under the Indus Broadband brand. The typical Pakistani ISP operates across a dealer hierarchy — a main company (PyroNet/Indus Broadband) sells internet packages through a network of independent dealers who in turn may have sub-dealers. Each dealer manages their own customer base, collects payments, and is accountable for their customers' accounts. PyroRadius was purpose-built to support this exact model.

Key business realities that shaped the design:

  • Dealer accountability: Dealers must only see and manage their own customers. Scoping is not optional — it is a hard security requirement enforced at every database query.
  • WhatsApp as the primary communication channel: In Pakistan, WhatsApp is ubiquitous. Invoice delivery, expiry reminders, and payment receipts are sent via WhatsApp. Email is a secondary fallback.
  • PPPoE-dominant network: Most residential and SME customers connect via PPPoE over fiber (FTTH). RADIUS authentication through FreeRADIUS is the authoritative access gate. The billing system must be the single source of truth for RADIUS credentials and policy.
  • Cash-dominant collections: Most payments are collected in cash by dealers or sub-dealers. The system must record these accurately with a full ledger trail.
  • OLT-based FTTH rollout: The network uses GPON OLTs (Optical Line Terminals). PyroRadius integrates with OLTs to poll ONT (Optical Network Terminal) signal levels and port assignments, giving NOC staff and engineers real-time fiber health data.

Who It's For

Role Description
Super Admin PyroNet Solutions internal staff. Full access to everything, including system settings, company profiles, all dealers, all customers.
Admin Senior operational staff. Manages dealers, can view as any dealer, manages packages and NAS devices. Cannot access certain system-level settings.
Dealer Independent resellers. See only their own customers, issue invoices, record payments, manage sub-dealers. Permissions are explicitly granted per key.
Sub Dealer Under a dealer. Restricted view of dealer's customers, typically limited to payment recording and status checks.
Customer Portal Users End customers who log in at /portal to view their own account, invoices, and connection status.
Field Engineers Technicians managed via the Engineer module. Can view assigned tickets and customer installation details.

Key Features

Billing & Finance

  • Automated invoice generation — monthly invoice batches generated by command or scheduler, with pro-rata support for mid-cycle activations.
  • Payment recording — supports multiple payment methods (cash, bank transfer, online). Payments are applied to oldest outstanding invoices first.
  • Ledger system — double-entry-style ledger entries (ledger_entries table) provide a complete financial history per customer, with running balance.
  • Invoice PDF export — invoices rendered to PDF via DomPDF with company branding from company_profiles.
  • Bulk recharge — batch-apply renewals to multiple customers simultaneously.
  • Overpaid invoice healing — HealOverpaidInvoices command reconciles customers where total payments exceed total invoices, correcting ledger imbalances.
  • Billing archive — old billing records cycled into billing_archives for performance, accessible via BillingArchiveController.
  • Dealer financial isolation — each dealer's financial records are scoped independently; dealer commission and package pricing are defined in the dealer_package pivot table.

RADIUS & Network Access Control

  • FreeRADIUS integration — PyroRadius writes directly to the FreeRADIUS schema tables (radcheck, radreply, radgroupreply, radusergroup, radacct) hosted in the same PostgreSQL instance.
  • Customer sync — RadiusService::syncCustomer() pushes PPPoE username/password and group assignment to RADIUS on every relevant customer change.
  • Package sync — RadiusService::syncPackage() writes speed attributes (rate-limit, burst) to radgroupreply for each package's radius group.
  • Connection types — PPPoE (id:1), Static IP (id:2), CIR (id:3) each have different RADIUS attribute sets.
  • Expired customer disconnect — KickExpiredOnline command disconnects PPPoE sessions for customers whose accounts have expired using RADIUS CoA/Disconnect-Messages via MikroTik API.
  • Ghost session cleanup — CloseGhostSessions identifies and terminates accounting sessions in radacct that have no corresponding live connection.

MikroTik & Router Integration

  • RouterOS API — connects to MikroTik routers via port 8728 using the evilfreelancer/routeros-api-php library.
  • Live traffic polling — PollTraffic command reads per-customer traffic counters from MikroTik NAS devices and stores in customer_traffic_readings.
  • NAS port polling — PollNasPorts maps which PPPoE sessions are active on which NAS port at any given time.
  • SNMP fallback — if RouterOS API is unavailable, MikroTikService falls back to SNMP for traffic data collection.
  • NAS health monitoring — RecordSysStats records CPU, memory, and uptime from each NAS. Health trends shown on the Health dashboard page.
  • Graph targets — administrators can define GraphTarget entries to track specific interface traffic over time, displayed in the Graphs module.

OLT / FTTH Management

  • OLT inventory — olts table tracks all Optical Line Terminals with their management IPs and credentials.
  • ONT cache — PollOltOnts command polls each OLT and populates ont_cache with all discovered ONTs, their serial numbers, ports, and signal levels.
  • Signal monitoring — PollSignal records ONT signal strength (Rx power in dBm) over time into signal_readings. Alerts when signal drops below threshold.
  • Customer ONT assignment — customers have ont_serial, ont_port, rx_power fields. SyncOntAssignments matches unassigned ONTs to customers by serial number.
  • OLT dashboard — the Olts page in the admin UI shows all OLTs, their ONT counts, and signal health summaries.

WhatsApp Notifications

  • Template-based messaging — whatsapp_templates table stores parameterized message templates for invoices, payment receipts, expiry reminders, and custom campaigns.
  • OpenWA integration — WhatsAppService sends messages via an OpenWA (WhatsApp Web automation) session running locally or on the server.
  • Log driver — during development or when OpenWA is unavailable, messages are written to whatsapp_logs table for auditing without actual transmission.
  • Bulk campaigns — the Campaigns module allows broadcast messages to filtered customer segments. CampaignRecipient tracks per-customer delivery status.
  • Automatic triggers — invoice generation, payment recording, and expiry events automatically queue WhatsApp notifications via Redis-backed jobs.
  • WhatsApp dashboard — NotificationDashboardController provides delivery statistics, failure analysis, and log browsing.

Dealer Hierarchy Management

  • Four-level hierarchy — super_admin → admin → dealer → sub_dealer.
  • Dealer package pricing — the dealer_package pivot allows each dealer to have custom pricing for each package they are permitted to sell.
  • View As feature — admins can impersonate any dealer's view to diagnose issues without logging out.
  • Sub-dealer management — dealers create and manage their sub-dealers, assign customers, and set permissions within their own scope.
  • Commission tracking — dealer financial reports show collection totals per dealer per period.

Customer Portal

  • Separate authentication — customers log in at /portal with their own credentials (not admin credentials).
  • Account overview — customers view their current package, expiry date, connection status, and outstanding balance.
  • Invoice history — customers can download their own invoices as PDF.
  • Complaint tickets — customers can raise support tickets through the portal.

Health Monitoring & Scheduler

  • Health dashboard — aggregated view of NAS device status, RADIUS server health, queue worker status, and command execution history.
  • DB-driven scheduler — cron_jobs table stores scheduled command definitions with cron expressions, managed via the Health UI. The main kernel.php scheduler reads this table and dispatches commands accordingly.
  • Audit logs — every create/update/delete action in the system is recorded in audit_logs with the acting user, IP address, model type, model ID, old values, and new values. Pruned periodically by PruneAuditLogs.

TR-069 Device Provisioning

  • GenieACS integration — GenieAcsService communicates with a GenieACS TR-069 server to provision and monitor CPE devices.
  • Device inventory — customer_acs_devices table links TR-069 device records to customer accounts.
  • Remote provisioning — administrators can push configuration parameters to CPE devices directly from the customer detail page.

Reporting

  • Billing reports — revenue summaries by period, dealer, package, and connection type.
  • Customer reports — churn analysis, new activations, expiry forecasts.
  • Traffic reports — bandwidth consumption per customer and per NAS.
  • Export — reports exportable to Excel via phpoffice/phpspreadsheet.
  • Import — bulk customer import via Excel using ImportController.

Technology Stack Summary

Layer Technology Version
Language PHP 8.3
Framework Laravel 13.8
Frontend Bridge Inertia.js v2.0
Frontend Framework React 18.2
CSS Framework Tailwind CSS v3.2
Database PostgreSQL 16
Cache / Queue Redis 7
HTTP Server Nginx latest stable
PHP Process Manager PHP-FPM 8.3
Process Supervisor Supervisor system
Build Tool Vite v8.0
PDF Generation DomPDF ^3.1
Excel I/O PhpSpreadsheet ^5.7
RouterOS API evilfreelancer/routeros-api-php ^1.7
Icon Library Lucide React ^1.16
Charts Recharts ^3.8
UI Components Headless UI ^2.0
HTTP Client (JS) Axios ^1.16
Route Helper (JS) Ziggy ^2.0
Auth Laravel Sanctum ^4.0

Deployment Information

Item Value
Production Server Ubuntu VPS, IP: your-server-ip
Application Root /var/www/pyroradius/
PHP-FPM Socket /run/php/php8.3-fpm.sock
Nginx Config /etc/nginx/sites-available/pyroradius
Supervisor Config /etc/supervisor/conf.d/pyroradius-worker.conf
Built Assets /var/www/pyroradius/public/build/
Storage Link /var/www/pyroradius/public/storage → /var/www/pyroradius/storage/app/public
Log Files /var/www/pyroradius/storage/logs/laravel.log
Queue Workers Multiple workers via Supervisor, redis connection
Backup Destination Defined in BackupRun command configuration
RADIUS Database Same PostgreSQL 16 instance, accessed by FreeRADIUS
FreeRADIUS Installed on same VPS, reads rad* tables from PostgreSQL

Default Admin Credentials (Change Immediately in Production)

Field Value
Email admin@pyronet.com.pk
Password change-me-on-first-login
Role super_admin

CRITICAL: Change the default admin password immediately after first login. Rotate it on any suspected breach.

Version History

Version Date Notes
Initial Release 2024 (est.) Core billing, RADIUS, MikroTik integration
OLT Module 2024 GPON OLT polling, ONT signal monitoring added
WhatsApp Campaigns 2025 Bulk campaign module, OpenWA integration
TR-069 / GenieACS 2025 CPE provisioning via GenieACS
Billing Archive 2025 Archive system for historical billing performance
Engineer Module 2025 Field engineer team management and ticket dispatch
Customer Portal 2025 End-customer self-service portal at /portal
DB-Driven Scheduler 2025 cron_jobs table, UI-managed from Health page
Graph Targets 2026 Custom interface traffic graph tracking
Documentation 2026-07-13 This documentation set created

Version numbers follow internal PyroNet conventions. There is no public semver release track; releases are managed by git branches on the production server.

Key Contacts

Role Name Contact
Founder / Lead Developer Ammar PyroNet Solutions, Lahore
System Administrator TBD —
Network Operations TBD —
Dealer Support Lead TBD —

Fill in contact details as team roles are formalized. All production server access should be documented in a separate, access-controlled credential store — not in this file.

This document is maintained by PyroNet Solutions. For technical deep-dives, refer to the other files in this MASTER_DOCUMENTATION directory.