ISP Portal — Master Module Reference

ISP Portal — Master Module Reference

Comprehensive module catalog for the NowaCRM ISP/Partner/Employee unified portal. Modules are organized by domain, prioritized by implementation phase, and mapped to the tenant hierarchy.

---

Table of Contents

1. Module Architecture Overview
2. Administration Modules
3. CRM & Subscriber Management
4. Service Catalog & Provisioning
5. Billing & Financial Management
6. Network Management (OSS)
7. Inventory & Asset Management
8. Support & Operations
9. Communication & Messaging
10. Reporting & Analytics
11. Partner & Reseller Management
12. Map & Coverage Management
13. Implementation Priority Matrix
14. Database Schema Implications

---

1. Module Architecture Overview

Portal Access by User Type

User Type	Guard	Sees	Creates	Manages
ISP Admin (user_type=2)	app	Full subtree data	Partners, Employees, Plans, Subscribers	Everything under ISP tenant
Partner (user_type=3)	app	Own subtree data	Sub-partners, Employees, Subscribers	Own org + children
Employee (user_type=4)	app	Assigned org subtree	Per RBAC permissions	Per RBAC permissions

Scoping Pattern

All modules follow the established hierarchy scoping:

• Read queries: whereIn('tenant_id', $subtreeIds) via BaseController::subtreeQuery()
• Write operations: tenant_id = authenticated user's tenant (write safety)
• Org filter: Per-page <x-org-filter /> re-scopes DataTable via AJAX
• RBAC: Employees restricted by assigned permissions; ISP/Partner users have full access within their subtree

Module Naming Convention

Route:      isp.{module}.{action}        → isp.subscribers.create
Controller: ISP\{Module}Controller        → ISP\SubscriberController
View:       isp/{module}/{action}.blade   → isp/subscribers/create.blade.php
JS:         assets/js/isp/{module}.js     → assets/js/isp/subscribers.js

---

2. Administration Modules

2.1 Organization Settings

Purpose: Manage the ISP or Partner organization's business profile, branding, and operational settings.

Field	Description
Route	isp.settings.*
Controller	ISP\SettingsController
Access	ISP Admin, Partner (own org only)
Tables	tenants, isp_profiles, isp_settings, isp_contacts

Features:

• Business profile (company name, registration number, GST/tax ID, address)
• Branding (logo upload, portal color theme, custom domain alias)
• Contact information (support email, phone, physical address)
• Operational settings (timezone, currency, date format, fiscal year start)
• Invoice template customization (header, footer, terms & conditions)
• Notification preferences (email, SMS, webhook triggers)

Sub-pages:

• isp/settings/profile — Business profile form
• isp/settings/branding — Logo, theme, portal customization
• isp/settings/billing — Invoice templates, tax config, payment terms
• isp/settings/notifications — Alert thresholds, channel preferences

---

2.2 User & Access Management (RBAC)

Purpose: Manage employees, roles, and granular permissions within the ISP tenant boundary.

Field	Description
Route	isp.roles.*, isp.permissions.*
Controller	ISP\RoleController, ISP\PermissionController
Access	ISP Admin only (RBAC management is ISP-level)
Tables	roles, permissions, role_permissions, user_roles

Features:

• Role Management: Create/edit/delete roles within tenant scope
  • Predefined templates: Admin, Manager, Support Agent, Billing Agent, NOC Technician, Read-Only
  • Custom role creation with granular permission assignment
  • Role cloning for quick setup
• Permission Groups:
  • subscribers.* — view, create, edit, delete, suspend, activate, disconnect
  • billing.* — view invoices, create payments, issue refunds, manage wallets
  • network.* — view NAS, manage IP pools, view RADIUS sessions
  • support.* — view tickets, assign tickets, close tickets
  • reports.* — view dashboards, export data, view financials
  • partners.* — view, create, edit sub-partners
  • settings.* — manage org settings, branding, notifications
• Employee Assignment: Assign roles to employees, bulk role changes
• Audit Trail: Log all permission changes with before/after snapshots

---

2.3 Audit Logs

Purpose: Complete audit trail of all administrative and operational actions within the tenant.

Field	Description
Route	isp.audit-logs.*
Controller	ISP\AuditLogController
Access	ISP Admin, Employees with audit.view permission
Tables	audit_logs

Features:

• Filterable log viewer with DataTable (user, action, entity, timestamp)
• Entity-level diff view (before/after JSON comparison)
• Export to CSV/PDF
• Filters: date range, user, action type, entity type, org filter
• Retention policy settings (auto-purge after N days)
• Critical action highlighting (deletions, permission changes, financial actions)

Log Categories:

• Authentication: login, logout, failed attempts, password changes
• CRUD: create/update/delete on all entities
• Financial: payment processing, refunds, wallet adjustments
• Network: NAS config changes, IP pool modifications
• System: settings changes, role/permission modifications

---

2.4 API & Integration Management

Purpose: Manage API tokens, webhooks, and third-party integrations.

Field	Description
Route	isp.api-tokens.*, isp.webhooks.*
Controller	ISP\ApiTokenController, ISP\WebhookController
Access	ISP Admin only
Tables	api_tokens, webhooks (new)

Features:

• API token generation with permission scoping (read-only, write, full)
• Token rotation and expiry management
• Usage statistics per token (requests/day, last used)
• Webhook endpoints: subscribe to events (subscriber.created, payment.received, etc.)
• Webhook delivery logs with retry mechanism
• Integration catalog: payment gateways, SMS providers, RADIUS, monitoring tools

---

3. CRM & Subscriber Management

3.1 Subscriber Management

Purpose: Core module for managing end-customer (subscriber) lifecycle from lead to active service.

Field	Description
Route	isp.subscribers.*
Controller	ISP\SubscriberController
Access	All ISP portal users (RBAC-scoped)
Tables	subscribers, subscriber_profiles, subscriber_documents (new)

Features:

• Subscriber List: DataTable with org filter, status badges, quick actions
  • Columns: ID, Name, Username (PPPoE/Hotspot), Plan, Status, Balance, Expiry, Created
  • Bulk actions: suspend, activate, disconnect, change plan, send notification
  • Advanced filters: status, plan, expiry range, balance range, area, partner
• Subscriber Registration:
  • Multi-step wizard: Personal Info → Service Selection → Installation → Review
  • Personal: name, email, phone, address (with map pin), government ID
  • Service: plan selection, connection type (PPPoE/DHCP/Static/Hotspot), IP assignment
  • Installation: installation date, assigned technician, ONU/CPE serial, location coordinates
  • KYC: document upload (ID proof, address proof), digital signature
• Subscriber Profile:
  • Overview dashboard: current plan, balance, usage chart, session status, recent tickets
  • Service tab: active plan details, plan change history, connection parameters
  • Billing tab: invoices, payments, wallet balance, transaction history
  • Documents tab: uploaded KYC documents with verification status
  • Sessions tab: live and historical RADIUS sessions with traffic stats
  • Tickets tab: support ticket history
  • Logs tab: audit trail for this subscriber
• Lifecycle Actions:
  • Activate, Suspend (manual/auto), Disconnect, Reconnect
  • Plan change (immediate or scheduled)
  • Credit adjustment (add/deduct from wallet)
  • Password reset (PPPoE/Hotspot credentials)
  • Move/relocate (change address and ONU)

Statuses: lead → pending_installation → active → suspended → disconnected → terminated

---

3.2 Lead Management

Purpose: Track potential subscribers from inquiry to conversion.

Field	Description
Route	isp.leads.*
Controller	ISP\LeadController
Access	All ISP portal users (RBAC-scoped)
Tables	leads (new)

Features:

• Lead capture form (name, phone, email, address, interest, source)
• Lead status pipeline: New → Contacted → Site Survey → Quoted → Won/Lost
• Assignment to sales/installation team
• Follow-up scheduling with reminders
• Conversion to subscriber (pre-fills registration form)
• Source tracking: website, referral, partner, walk-in, campaign
• Kanban board view + DataTable list view
• Lead analytics: conversion rate, average time-to-convert, source performance

---

3.3 Customer Groups & Tags

Purpose: Organize subscribers into groups for bulk operations and targeted actions.

Field	Description
Route	isp.customer-groups.*
Controller	ISP\CustomerGroupController
Access	ISP Admin, Employees with permission
Tables	customer_groups, customer_group_members (new)

Features:

• Static groups (manually assigned subscribers)
• Dynamic/smart groups (rule-based: plan type, area, balance range, expiry range)
• Tags: lightweight labels for quick categorization
• Bulk operations on groups: send notification, change plan, apply credit, generate invoices
• Group-based reporting

---

4. Service Catalog & Provisioning

4.1 Plan Management

Purpose: Define internet service plans (tariffs) with bandwidth, data caps, pricing, and FUP rules.

Field	Description
Route	isp.plans.*
Controller	ISP\PlanController
Access	ISP Admin
Tables	plans, plan_profiles (new)

Features:

• Plan Definition:
  • Name, description, plan code
  • Speed: download/upload (Mbps), burst speed/duration
  • Data: unlimited or capped (GB), FUP speed after cap
  • Pricing: monthly/quarterly/half-yearly/yearly, setup fee, tax configuration
  • Validity: days-based (30/90/180/365) or calendar-based (month-end)
  • Connection type: PPPoE, DHCP, Static IP, Hotspot
• RADIUS Profile Mapping:
  • Bandwidth attributes (Mikrotik-Rate-Limit, WISPr-Bandwidth-Max)
  • IP pool assignment
  • Session limits (concurrent sessions, idle timeout)
  • VLAN/service-type attributes
• Plan Categories: Residential, Business, Enterprise, Hotspot, Dedicated
• Plan Lifecycle: Draft → Active → Deprecated (no new signups) → Archived
• Promotional Plans: Time-limited plans with auto-revert to base plan
• Add-ons: Data top-up packs, speed boost packs, static IP add-on

---

4.2 IP Address Management (IPAM)

Purpose: Manage IP address pools, assignments, and subnets for subscriber provisioning.

Field	Description
Route	isp.ip-pools.*
Controller	ISP\IpPoolController
Access	ISP Admin, NOC team
Tables	ip_pools, ip_assignments (new)

Features:

• Pool definition: name, subnet (CIDR), gateway, DNS servers, VLAN
• Pool types: dynamic (DHCP/RADIUS), static (manually assigned), hotspot
• Visual subnet utilization map (used/free/reserved)
• Static IP assignment to subscriber with reservation
• Pool-to-NAS association (which pools available on which NAS devices)
• IPv4 and IPv6 support
• Conflict detection (overlapping subnets, duplicate assignments)
• Bulk import from CSV

---

4.3 NAS / BNG Device Management

Purpose: Manage network access servers (routers, BNGs, OLTs) that connect to RADIUS.

Field	Description
Route	isp.nas.*
Controller	ISP\NasController
Access	ISP Admin, NOC team
Tables	nas_devices (new)

Features:

• NAS registration: name, IP, RADIUS secret, type (Mikrotik/Cisco/Huawei/Ubiquiti), vendor
• NAS grouping by location/POP
• Status monitoring: last seen (from RADIUS accounting), reachability check
• Associated IP pools and subscriber counts
• CoA (Change of Authorization) support: disconnect user, change bandwidth live
• Bulk CoA: push profile changes to all active sessions on a NAS
• NAS-level statistics: active sessions, bandwidth utilization

---

4.4 FreeRADIUS Integration

Purpose: Manage RADIUS authentication, authorization, and accounting policies.

Field	Description
Route	isp.radius.*
Controller	ISP\RadiusController
Access	ISP Admin, NOC team
Tables	radcheck, radreply, radgroupcheck, radgroupreply, radusergroup, radacct, radius_accounting

Features:

• Online Sessions Viewer:
  • Real-time active session list from radacct (where acctstoptime IS NULL)
  • Columns: username, NAS, IP, MAC, session duration, upload/download, input/output rate
  • Actions: disconnect session (CoA), view session history
  • Auto-refresh with configurable interval
• Session History:
  • Historical sessions with date range filter
  • Per-subscriber session log with aggregate traffic
  • Export session data to CSV
• RADIUS Attributes Manager:
  • View/edit check and reply attributes per subscriber
  • Group profiles with shared attributes
  • Attribute templates (common vendor-specific configurations)
• Authentication Log:
  • Failed auth attempts with reasons (wrong password, disabled account, expired plan)
  • Brute force detection alerts

---

5. Billing & Financial Management

5.1 Invoice Management

Purpose: Generate, track, and manage subscriber invoices.

Field	Description
Route	isp.invoices.*
Controller	ISP\InvoiceController
Access	All ISP portal users (RBAC-scoped)
Tables	invoices, invoice_items (new)

Features:

• Invoice Generation:
  • Auto-generation on plan activation, renewal, or scheduled billing cycle
  • Manual invoice creation for ad-hoc charges
  • Batch generation: generate invoices for all subscribers due on a date
  • Prorated invoices for mid-cycle plan changes
• Invoice Details:
  • Invoice number (auto-sequence per tenant), date, due date
  • Line items: plan charges, setup fee, add-ons, taxes, discounts, credits
  • Tax calculation: GST/VAT with configurable rates and tax groups
  • Payment status: unpaid → partially paid → paid → overdue → void
• Invoice Actions:
  • Send via email / SMS / WhatsApp
  • Print / Download PDF
  • Apply payment, partial payment
  • Issue credit note / refund
  • Void / cancel
• Recurring Billing:
  • Configurable billing cycles per plan
  • Grace period before suspension
  • Auto-suspend on overdue (configurable days)
  • Dunning workflow: reminder → warning → suspension → disconnection

---

5.2 Payment Processing

Purpose: Record and process subscriber payments through multiple channels.

Field	Description
Route	isp.payments.*
Controller	ISP\PaymentController
Access	All ISP portal users (RBAC-scoped)
Tables	payments, wallet_transactions

Features:

• Payment Methods:
  • Cash (at office/partner location)
  • Online: payment gateway integration (Razorpay, PhonePe, UPI, Paytm)
  • Bank transfer (manual reconciliation)
  • Wallet/prepaid balance deduction
  • Cheque (with clearance tracking)
• Payment Recording:
  • Manual entry: amount, method, reference number, date, subscriber
  • Auto-match to oldest unpaid invoice or specific invoice
  • Partial payment support
  • Payment receipt generation (PDF)
• Reconciliation:
  • Bank statement import (CSV)
  • Auto-matching algorithm (amount + reference number)
  • Unmatched payment queue for manual resolution
• Refunds:
  • Full or partial refund to wallet or original payment method
  • Refund reason tracking
  • Approval workflow (optional)

---

5.3 Wallet / Prepaid System

Purpose: Prepaid balance management for subscribers — the primary billing model for ISPs.

Field	Description
Route	isp.wallets.*
Controller	ISP\WalletController
Access	ISP Admin, Billing agents
Tables	wallets, wallet_transactions

Features:

• Subscriber wallet balance view and history
• Credit operations: top-up, promotional credit, adjustment
• Debit operations: plan renewal, add-on purchase, penalty
• Auto-debit on plan renewal date
• Low balance alerts (configurable threshold)
• Wallet-to-wallet transfer (subscriber to subscriber)
• Bulk wallet operations (credit all subscribers in a group)
• Transaction ledger with running balance

---

5.4 Tax Configuration

Purpose: Configure tax rules applicable to services and invoices.

Field	Description
Route	isp.tax.*
Controller	ISP\TaxController
Access	ISP Admin
Tables	tax_groups, tax_rates (new)

Features:

• Tax group definition (e.g., "GST 18%", "No Tax")
• Multiple tax rates per group (CGST + SGST or IGST)
• Tax applicability rules: by service type, plan category, subscriber location
• Tax-inclusive vs tax-exclusive pricing
• Tax reports: collection summary, pending filings

---

6. Network Management (OSS)

6.1 Network Map / Topology

Purpose: Visual representation of network infrastructure — POPs, OLTs, switches, and connections.

Field	Description
Route	isp.network.topology
Controller	ISP\NetworkController
Access	ISP Admin, NOC team
Tables	network_nodes, network_links (new)

Features:

• Interactive network topology diagram (D3.js or vis.js)
• Node types: POP, OLT, Switch, Access Point, BNG/Router
• Link types: fiber, ethernet, wireless
• Status overlay: green/red/amber based on monitoring data
• Click-through to device details and connected subscribers
• Drag-and-drop topology editor

---

6.2 Bandwidth Monitoring

Purpose: Monitor real-time and historical bandwidth usage across the network.

Field	Description
Route	isp.network.bandwidth
Controller	ISP\BandwidthController
Access	ISP Admin, NOC team
Tables	bandwidth_samples (new, or derived from RADIUS accounting)

Features:

• Per-NAS bandwidth graphs (5-min, hourly, daily aggregation)
• Per-subscriber bandwidth usage charts
• Peak usage detection and alerts
• Bandwidth utilization heatmap by time-of-day
• Top consumers list (heaviest users)
• 95th percentile calculation for upstream billing

---

6.3 SNMP Monitoring (Future)

Purpose: Poll network devices via SNMP for interface stats, uptime, and health.

Field	Description
Route	isp.network.monitoring
Controller	ISP\MonitoringController
Access	ISP Admin, NOC team
Tables	device_metrics (new)

Features:

• SNMP community string management per device
• Interface utilization graphs
• Device uptime tracking
• Threshold-based alerting (interface down, high CPU, high memory)
• Integration with external NMS (Zabbix, LibreNMS) via API

---

7. Inventory & Asset Management

7.1 CPE / ONU Device Inventory

Purpose: Track customer premises equipment — ONUs, routers, ONTs, and other devices.

Field	Description
Route	isp.inventory.devices
Controller	ISP\DeviceInventoryController
Access	ISP Admin, Inventory team
Tables	devices, device_assignments (new)

Features:

• Device catalog: model, manufacturer, type (ONU/Router/ONT/Switch/AP)
• Individual device tracking: serial number, MAC address, purchase date, warranty expiry
• Device status: in-stock → assigned → installed → faulty → returned → decommissioned
• Assignment to subscriber with installation record
• Batch import from CSV (bulk device registration)
• Device search by serial/MAC
• Stock level alerts (low stock threshold per model)

---

7.2 Fiber / Cable Management (Future)

Purpose: Track fiber routes, splice points, and cable infrastructure.

Field	Description
Route	isp.inventory.fiber
Controller	ISP\FiberController
Access	ISP Admin, Field team
Tables	fiber_routes, splice_points, fiber_cores (new)

Features:

• Fiber route definition on map (polyline drawing)
• Core allocation tracking (which core → which subscriber)
• Splice point management with photo documentation
• Cable specification (single-mode, multi-mode, core count)
• Loss measurement records per splice
• Port mapping for OLTs and distribution boxes

---

8. Support & Operations

8.1 Ticketing System

Purpose: Customer support ticketing for issue tracking and resolution.

Field	Description
Route	isp.tickets.*
Controller	ISP\TicketController
Access	All ISP portal users (RBAC-scoped)
Tables	tickets, ticket_comments, ticket_attachments (new)

Features:

• Ticket Creation:
  • Source: portal, email, phone (manual entry), subscriber self-service
  • Categories: connectivity, billing, speed, installation, general inquiry
  • Priority: low, medium, high, critical
  • Assignment to team/individual
  • Link to subscriber account
• Ticket Workflow:
  • Status: open → in-progress → waiting-on-customer → resolved → closed → reopened
  • SLA tracking: response time, resolution time per priority
  • Escalation rules: auto-escalate if SLA breached
  • Internal notes vs customer-visible comments
  • File attachments (screenshots, photos)
• Ticket List:
  • DataTable with org filter
  • Filters: status, priority, category, assignee, date range
  • Bulk actions: assign, change priority, close
• Dashboard:
  • Open tickets by priority
  • SLA compliance percentage
  • Average resolution time
  • Agent workload distribution

---

8.2 Task & Work Order Management

Purpose: Schedule and track field operations like installations, maintenance, and repairs.

Field	Description
Route	isp.work-orders.*
Controller	ISP\WorkOrderController
Access	ISP Admin, Field team managers
Tables	work_orders, work_order_items (new)

Features:

• Work order types: installation, relocation, repair, disconnection, maintenance
• Scheduling: date, time slot, assigned technician
• Linked to subscriber and/or ticket
• Checklist items per work order type
• Photo upload (before/after installation)
• Technician status updates: en-route → on-site → completed
• Calendar view for scheduling
• Map view for daily route planning

---

8.3 Scheduled Jobs & Maintenance

Purpose: Manage automated jobs and planned maintenance windows.

Field	Description
Route	isp.scheduled-jobs.*
Controller	ISP\ScheduledJobController
Access	ISP Admin
Tables	scheduled_jobs (new)

Features:

• Job scheduler UI: billing runs, report generation, auto-suspend, cleanup jobs
• Maintenance window calendar: notify affected subscribers
• Job execution logs with status (success/failure/partial)
• Manual trigger for on-demand execution
• Cron expression builder (visual)

---

9. Communication & Messaging

9.1 Notification Center

Purpose: Centralized notification management for all subscriber and internal communications.

Field	Description
Route	isp.notifications.*
Controller	ISP\NotificationController
Access	ISP Admin, Employees with permission
Tables	notifications, notification_templates (new)

Features:

• Channels: Email, SMS, WhatsApp, In-app push, Webhook
• Notification Types:
  • Transactional: payment received, invoice generated, plan activated/expired
  • Operational: suspension warning, disconnection notice, maintenance alert
  • Marketing: promotional offers, plan upgrade suggestions
  • System: job completion, threshold alerts, security events
• Template Management:
  • WYSIWYG template editor with variable placeholders
  • Variables: {subscriber_name}, {plan_name}, {amount}, {due_date}, etc.
  • Templates per channel (email HTML, SMS text, WhatsApp format)
  • Language/locale support
• Bulk Messaging:
  • Send to all subscribers, specific plan, group, area, or custom filter
  • Schedule for future delivery
  • Delivery report tracking

---

9.2 SMS Gateway Integration

Purpose: Configure SMS provider for transactional and bulk SMS delivery.

Field	Description
Route	isp.settings.sms
Controller	ISP\SmsSettingsController
Access	ISP Admin
Tables	sms_configs, sms_logs (new)

Features:

• SMS provider setup: API credentials, sender ID, DLT template IDs (India-specific)
• Supported providers: MSG91, Twilio, Textlocal, custom HTTP API
• SMS delivery logs with status (sent, delivered, failed)
• SMS balance / credit tracking
• DND (Do Not Disturb) compliance

---

9.3 Email Configuration

Purpose: Configure SMTP/transactional email for automated communications.

Field	Description
Route	isp.settings.email
Controller	ISP\EmailSettingsController
Access	ISP Admin
Tables	email_configs (new)

Features:

• SMTP configuration (host, port, encryption, credentials)
• Email service integration: Mailgun, SendGrid, Amazon SES
• From name and reply-to address per tenant
• Email delivery logs
• Bounce handling

---

10. Reporting & Analytics

10.1 Dashboard & KPIs

Purpose: Executive-level overview with key performance indicators.

Field	Description
Route	isp.dashboard
Controller	ISP\DashboardController
Access	All ISP portal users

Key Metrics (stat cards):

• Total subscribers (active/suspended/disconnected trend)
• Monthly recurring revenue (MRR)
• Collection efficiency (collected vs billed)
• New activations this month
• Churn rate (disconnections / total active)
• Average revenue per user (ARPU)
• Outstanding receivables
• Active online sessions

Charts:

• Subscriber growth trend (12-month line chart)
• Revenue trend (12-month bar chart)
• Plan distribution (pie/donut chart)
• Top 10 areas by subscriber count
• Daily new connections vs disconnections

---

10.2 Financial Reports

Purpose: Detailed financial reporting for revenue, collections, and outstanding analysis.

Field	Description
Route	isp.reports.financial.*
Controller	ISP\FinancialReportController
Access	ISP Admin, Billing team

Reports:

• Revenue Report: Monthly/quarterly/yearly revenue breakdown by plan, area, partner
• Collection Report: Payments received grouped by method, date, collector
• Outstanding Report: Aging analysis (0-30, 31-60, 61-90, 90+ days overdue)
• Tax Report: Tax collected by type and period (GST return helper)
• Commission Report: Partner-wise commission earned/paid
• Profit & Loss: Revenue minus operational costs per period
• Day-wise Collection: Daily cash flow in/out summary

Export Options: PDF, Excel (XLSX), CSV

---

10.3 Subscriber Reports

Purpose: Subscriber lifecycle and engagement analytics.

Field	Description
Route	isp.reports.subscribers.*
Controller	ISP\SubscriberReportController
Access	ISP Admin, Employees with permission

Reports:

• Status Summary: Active/suspended/disconnected counts with percentage
• Plan-wise Distribution: Subscriber count per plan
• Area-wise Distribution: Subscribers per geographic area/zone
• Expiry Report: Subscribers expiring in next 7/15/30 days
• New Connections: Daily/weekly/monthly new activations
• Churn Report: Disconnections with reasons
• Usage Report: Top consumers, average usage per plan
• KYC Compliance: Subscribers with/without verified documents

---

10.4 Network Reports

Purpose: Network performance and utilization reporting.

Field	Description
Route	isp.reports.network.*
Controller	ISP\NetworkReportController
Access	ISP Admin, NOC team

Reports:

• Session Report: Total sessions, average duration, concurrent peak
• Traffic Report: Total upload/download per period (from RADIUS accounting)
• NAS Utilization: Sessions per NAS, peak loading times
• IP Pool Utilization: Used/free per pool
• Authentication Failures: Failed login attempts with reasons
• Top Talkers: Heaviest bandwidth consumers

---

11. Partner & Reseller Management

11.1 Partner Hierarchy

Purpose: Manage the recursive partner/sub-partner network.

Field	Description
Route	isp.partners.*
Controller	ISP\PartnerController (existing, enhanced)
Access	ISP Admin, Partner (manages sub-partners)
Tables	tenants, users, partners

Existing Features (built):

• Partner CRUD with hierarchy tree
• Org filter scoping
• DataTable with parent column

Enhanced Features (planned):

• Partner profile detail page with business metrics
• Hierarchy tree visualization (org chart style)
• Partner-level dashboard (subscriber count, revenue, collection summary)
• Partner agreement/contract management
• Partner-specific plan/pricing overrides
• Geographic zone assignment

---

11.2 Commission & Revenue Sharing

Purpose: Define and track commission structures for partners.

Field	Description
Route	isp.commissions.*
Controller	ISP\CommissionController
Access	ISP Admin
Tables	commission_rules, commission_transactions (new)

Features:

• Commission rule definition: percentage or fixed amount per plan per partner level
• Tiered commissions: different rates based on subscriber count thresholds
• Commission calculation: auto-calculate on payment collection
• Commission statement generation per partner per period
• Settlement tracking: pending → approved → paid
• Multi-level commission (partner earns on sub-partner's collections too)

---

11.3 Partner Settlement

Purpose: Financial settlement between ISP and partners — reconcile collections and payables.

Field	Description
Route	isp.settlements.*
Controller	ISP\SettlementController
Access	ISP Admin
Tables	settlements, settlement_items (new)

Features:

• Settlement period definition (weekly/bi-weekly/monthly)
• Auto-generate settlement statement: collections by partner minus commission = payable to ISP
• Settlement approval workflow
• Payment recording against settlement
• Outstanding settlement tracking
• Settlement dispute handling

---

12. Map & Coverage Management

12.1 Coverage Map

Purpose: Visualize and manage service coverage areas on an interactive map.

Field	Description
Route	isp.coverage-map
Controller	ISP\CoverageMapController
Access	ISP Admin, Sales team
Tables	coverage_zones (new)

Features:

• Interactive map (Leaflet.js + OpenStreetMap)
• Coverage zone drawing: polygon/circle with zone name and status
• Zone status: planned → under-construction → active → retired
• Subscriber pin plotting (from address coordinates)
• POP/OLT location markers with coverage radius
• Fiber route overlay
• Heatmap: subscriber density by area
• Public-facing coverage check page (optional)

---

12.2 Area / Zone Management

Purpose: Define geographic areas for operational grouping of subscribers and assets.

Field	Description
Route	isp.areas.*
Controller	ISP\AreaController
Access	ISP Admin
Tables	areas (new)

Features:

• Area/zone hierarchy: City → Zone → Sub-zone → Building/Society
• Area assignment to subscribers and network nodes
• Area-wise subscriber count and revenue summary
• Area-based task/work order routing
• Technician territory assignment by area

---

13. Implementation Priority Matrix

Phase 1: Core Foundation (Current — Mostly Built)

Module	Status	Priority
Organization Settings	Partial (tenant settings exist)	HIGH
User & Access Management (RBAC)	Built (roles/permissions tables exist)	HIGH
Partner Management	Built (CRUD + hierarchy)	DONE
Employee Management	Built (CRUD + org assignment)	DONE
Org Filter	Built (per-page Select2 component)	DONE
Audit Logs	Table exists, viewer needed	HIGH
Dashboard (basic stats)	Built (4 stat cards + partner table)	DONE

Phase 2: Subscriber & Billing Core

Module	Status	Priority
Subscriber Management	Not started	CRITICAL
Plan Management	Not started	CRITICAL
Invoice Management	Not started	CRITICAL
Payment Processing	Not started	CRITICAL
Wallet / Prepaid System	Partial (tables exist)	HIGH
Tax Configuration	Not started	HIGH

Phase 3: Network & RADIUS

Module	Status	Priority
RADIUS Session Viewer	Partial (accounting table exists)	CRITICAL
NAS Device Management	Not started	HIGH
IP Address Management (IPAM)	Not started	HIGH
FreeRADIUS Attribute Manager	Not started	MEDIUM

Phase 4: Operations & Support

Module	Status	Priority
Ticketing System	Not started	HIGH
Work Order Management	Not started	MEDIUM
Notification Center	Not started	HIGH
SMS Gateway Integration	Not started	MEDIUM
Email Configuration	Not started	MEDIUM

Phase 5: Reporting & Analytics

Module	Status	Priority
Dashboard KPIs (enhanced)	Partial	HIGH
Financial Reports	Not started	HIGH
Subscriber Reports	Not started	HIGH
Network Reports	Not started	MEDIUM

Phase 6: Advanced Features

Module	Status	Priority
Lead Management	Not started	MEDIUM
Customer Groups & Tags	Not started	MEDIUM
Commission & Revenue Sharing	Not started	MEDIUM
Partner Settlement	Not started	MEDIUM
Coverage Map	Not started	LOW
Area / Zone Management	Not started	MEDIUM
CPE Device Inventory	Not started	MEDIUM
Network Topology	Not started	LOW
Bandwidth Monitoring	Not started	LOW
API & Integration Management	Not started	LOW
Fiber / Cable Management	Not started	LOW
Scheduled Jobs	Not started	LOW
SNMP Monitoring	Not started	LOW

---

14. Database Schema Implications

New Tables Required (by phase)

Phase 2 — Subscriber & Billing:

subscribers              — Core subscriber records
subscriber_profiles      — Extended subscriber data (KYC, address details)
subscriber_documents     — Uploaded documents (ID proof, photos)
plans                    — Service plan definitions
plan_profiles            — RADIUS profile mappings per plan
invoices                 — Generated invoices
invoice_items            — Line items per invoice
payments                 — Payment records
tax_groups               — Tax group definitions
tax_rates                — Individual tax rates

Phase 3 — Network:

nas_devices              — NAS/BNG device registry
ip_pools                 — IP address pool definitions
ip_assignments           — Individual IP assignments to subscribers

Phase 4 — Operations:

tickets                  — Support tickets
ticket_comments          — Ticket thread messages
ticket_attachments       — Attached files
work_orders              — Field work orders
work_order_items         — Work order checklist items
notifications            — Sent notifications log
notification_templates   — Message templates
sms_configs              — SMS provider configuration
sms_logs                 — SMS delivery logs
email_configs            — Email/SMTP configuration

Phase 5 — Reporting:

(No new tables — reports query existing tables with aggregation)

Phase 6 — Advanced:

leads                    — Sales leads
customer_groups          — Subscriber grouping
customer_group_members   — Group membership (pivot)
commission_rules         — Partner commission definitions
commission_transactions  — Calculated commissions
settlements              — Partner settlement records
settlement_items         — Settlement line items
coverage_zones           — Geographic coverage polygons
areas                    — Area/zone hierarchy
network_nodes            — Network topology nodes
network_links            — Network topology links
devices                  — CPE/ONU device inventory
device_assignments       — Device-to-subscriber assignment
fiber_routes             — Fiber cable routes
splice_points            — Fiber splice locations
fiber_cores              — Individual core tracking
bandwidth_samples        — Bandwidth utilization data
device_metrics           — SNMP polling data
scheduled_jobs           — Job scheduler records
webhooks                 — Webhook endpoint config

All New Tables Follow Tenant Scoping

Every new table includes:

tenant_id     BIGINT UNSIGNED NOT NULL  -- FK to tenants.id
-- Global scope: WHERE tenant_id = ? (for writes)
-- Subtree scope: WHERE tenant_id IN (?) (for reads via org filter)

---

References

• Industry Platforms Studied: Splynx, UISP (Ubiquiti), Sonar.software, Visp.net, Solunus, Powercode, Platanus
• Standards: TM Forum SID/eTOM frameworks (simplified for SMB ISP scale)
• NowaCRM Architecture: See docs/telecom-saas-architecture.md for full technical architecture
• RBAC Design: See docs/LIFECYCLE.md for role hierarchy and access rules
• Current Implementation: Phase 1 complete (Partner/Employee CRUD, Org Filter, Dashboard, Auth)