PyroRadius — Master Documentation¶

System: PyroRadius ISP Billing & RADIUS Management Company: PyroNet Solutions, Lahore, Pakistan Stack: Laravel 13 + Inertia.js v2 + React 18 + PostgreSQL 16 Last Updated: 2026-07-26 Version Documented: Production codebase as of 2026-07-26

I need to...	Go to
Understand the system from scratch	00 Project Overview → 01 Architecture
Set up the server / deploy	02 Installation → 31 Deployment
Fix a bug or outage right now	32 Troubleshooting
Understand billing logic	10 Billing System
Understand RADIUS / PPPoE	01 Architecture → 14 NAS Management
Understand the database schema	03 Database Architecture
Find a route / API endpoint	06 Routing Map → 09 API Documentation
Understand permissions / roles	08 Backend Architecture → 28 Security Audit
Work on the React frontend	07 Frontend Architecture
Understand customer management	12 Customer Management
Understand dealer / reseller system	13 Dealer System
Work with MikroTik / RouterOS	15 MikroTik
Work with TR-069 / ACS	16 TR-069
Work with WhatsApp integration	18 WhatsApp System
Understand background jobs / queues	26 Background Jobs
Write or run tests	30 Testing
Plan future work	33 Future Roadmap
Brief an AI agent on the project	AI_CONTEXT.md

Full Documentation Index¶

Foundation¶

00 Project Overview ¶

High-level introduction to PyroRadius. What it is, who uses it, why it was built, and the business context (PyroNet Solutions, ISP in Lahore, Pakistan).

01 System Architecture ¶

End-to-end architecture: how Nginx, PHP-FPM, PostgreSQL, Redis, FreeRADIUS, MikroTik, OLT, and WhatsApp fit together. Includes the RADIUS authentication flow and data flow diagrams.

02 Installation Guide ¶

Step-by-step server setup: Ubuntu, Nginx, PHP 8.3, PostgreSQL 16, Redis, Node 20, FreeRADIUS, Supervisor. Environment variable reference. First-run setup checklist.

03 Database Architecture ¶

All tables, columns, types, foreign keys, and indexes. Covers both the main pyroradius database and the radius (FreeRADIUS) database. ERD description, migration conventions.

Application Structure¶

06 Routing Map ¶

Every route in routes/web.php and routes/api.php with the controller method, middleware, and permission required. Organized by feature area.

07 Frontend Architecture ¶

React 18 + Inertia.js v2 + Tailwind CSS v3 setup. Component hierarchy, shared layouts, AppLayout and AuthLayout, usePage hook usage, permission helper can(), state management patterns, Vite build config.

08 Backend Architecture ¶

Laravel 13 service layer overview. All Services (BillingService, RadiusService, MikroTikService, WhatsAppService, AuditLogger, RouterOsService). Controller conventions, middleware stack, permission system (JSONB permissions column), role hierarchy.

09 API Documentation ¶

All AJAX / API endpoints (routes/api.php). Request/response format, authentication requirements, rate limiting, error codes.

Feature Documentation¶

10 Billing System ¶

Invoice generation (idempotent, period-based), payment application (excess applies to older invoices), customer recharge flow, expiry date extension, receipt generation, invoice number format (INV202506-00001), receipt format (RCP202506-00001), monthly billing cycle, GenerateMonthlyInvoices command.

12 Customer Management ¶

Customer CRUD, customer code generation (PR + 5-digit sequential), PPPoE/Static/CIR connection types, package assignment, dealer scoping, customer status (active/suspended/expired/terminated), ONT assignment, customer portal.

13 Dealer System ¶

Dealer hierarchy (super_admin → admin → dealer → sub_dealer), dealer registration, permission assignment, dealer balance and commission, sub-dealer management, CIR dealers.

14 NAS Management ¶

Network Access Server (NAS/BRAS) setup, RADIUS client configuration, NAS credentials (API user/password for MikroTik), NAS health monitoring, RADIUS accounting.

15 MikroTik ¶

RouterOS API integration, live traffic polling, customer disconnect via API, SNMP fallback, online session counting (RouterOsService), PPPoE profile management.

16 TR-069 ¶

TR-069 / CWMP ACS integration (currently disabled: ACS_ENABLED=false). CPE provisioning, remote configuration, ACS connection. Pages are partially built; this feature is not production-active.

18 WhatsApp System ¶

WhatsApp Business API integration, session management, message templates (recharge confirmation, expiry reminder, invoice), WhatsAppService, queue-based dispatch, whatsapp_enabled setting toggle.

19 Notification System ¶

In-app notifications, notification types, notification delivery (database + broadcast), notification read/unread state, notification preferences.

20 Campaign System ¶

Bulk WhatsApp campaigns, campaign targeting (by dealer, package, status), campaign scheduling, campaign history, delivery tracking.

21 Reports ¶

Available reports: collection summary, dealer-wise revenue, package-wise customers, expiry report, new activations, churn report. Export formats (Excel, PDF). Report scheduling.

22 Dashboard ¶

Dashboard stats: total customers, online count (RADIUS + MikroTik), today's collections, expiring soon. Online count architecture (Redis cache, RouterOsService, fallback). DashboardController, viewAs feature (admin views as dealer).

Operations & Infrastructure¶

24 Health System ¶

System health monitoring: NAS connectivity checks, RADIUS table health, Redis health, queue worker health, OLT connectivity. Health check endpoints and alerts.

25 Settings ¶

Settings table key-value store, all available setting keys (whatsapp_enabled, whatsapp_session_status, sms_enabled, etc.), admin UI for settings, how to read settings in code (Setting::get('key')).

26 Background Jobs ¶

All Artisan commands and queue jobs: SyncAllRadius, SyncOntAssignments, PollOltOnts, CloseGhostSessions, GenerateMonthlyInvoices, BackupRun, SendExpiryReminders. Supervisor configuration, queue drivers, job retry logic.

27 Imports ¶

Bulk customer import via Excel/CSV, import validation rules, import mapping, rollback on failure, import history log.

28 Security Audit ¶

Permission gate system, AuditLogger (all mutations logged with user, action, old value, new value), SQL injection prevention, XSS prevention, CSRF protection, PPPoE password plain-text requirement and why, rate limiting, production security checklist.

Development & Quality¶

30 Testing ¶

Current testing state (PHPUnit + Playwright installed, zero tests written — honest documentation). How to run tests. Testing strategy and priority order. Example PHPUnit test for BillingService. Example Playwright test for customer recharge. Test database setup. Mocking RADIUS, WhatsApp, MikroTik. Pre-production manual verification checklist.

31 Deployment ¶

Server architecture (single VPS). SSH access. Git workflow (feature branch, never push to master). Full deploy procedures for PHP-only, JS-only, migrations, and combined changes. Supervisor management. Nginx notes. PHP-FPM pool settings. Environment variable management. Backup strategy. Post-deploy verification checklist. Rollback procedure.

32 Troubleshooting ¶

Common issues organized by category: Authentication, Billing, RADIUS, MikroTik, OLT, WhatsApp, Queue, Database (lock timeouts, deadlocks), Performance. Diagnostic commands reference (laravel.log, queue, RADIUS tables, PostgreSQL, tinker).

33 Future Roadmap ¶

Immediate priorities (tests, staging, CI/CD). Short-term (TR-069, mobile app, WhatsApp 2-way, advanced reports, multi-NAS). Medium-term (self-service portal, payment gateway, franchise module, SLA monitoring). Long-term vision (multi-city, white-label, API-first, real-time WebSockets, AI churn prediction). Technical debt (remove .bak files, missing permission gates). Known bugs backlog.

AI Agent Reference¶

AI_CONTEXT.md ¶

The single most important file for AI assistants. Contains the complete project context in a structured format designed for rapid AI onboarding: architecture summary, absolute rules, stack versions, folder map, key files, business rules, naming conventions, deployment process, permission system, known issues, recently fixed issues, and AI assistant guidelines. Read this file first before asking any AI agent for help.

Documentation Conventions¶

File Naming¶

Files are numbered to indicate reading order and grouping:

00–09 — Foundation (overview, architecture, installation, database)
06–09 — Application structure (routing, frontend, backend, API)
10–22 — Feature documentation (one file per major feature)
24–28 — Operations (health, settings, jobs, imports, security)
30–33 — Development & quality (testing, deployment, troubleshooting, roadmap)
README.md — This index file
AI_CONTEXT.md — AI agent quick-start reference

Content Standards¶

Every file starts with a level-1 heading matching the file name
Command examples use code blocks with the language specified
Tables are used for reference information (routes, config options, error codes)
Warnings use a > **WARNING:** blockquote format
Known limitations or "not implemented yet" items are clearly labeled
Dates are in YYYY-MM-DD format

How to Contribute¶

Follow the existing file naming convention
Update this README.md index when adding a new file
Update AI_CONTEXT.md if you add a new service, change a business rule, or fix a known issue
Do not use placeholder text ("TBD", "coming soon") — either write the content or omit the section
Keep commands copy-pasteable and tested

Contact¶

PyroNet Solutions Lahore, Pakistan ISP & IT Services

For system access or documentation questions, contact the PyroNet Solutions development team.