ISP Solution - Network Services Management

A comprehensive ISP (Internet Service Provider) management system built with Laravel 12, featuring multi-tenancy, RADIUS authentication, MikroTik router integration, and IP address management (IPAM).

🎯 Project Overview

ISP Solution is a modern, production-ready platform designed to manage every aspect of an Internet Service Provider's operations. Built with Laravel 12 and wrapped in a beautiful Metronic Tailwind CSS interface, it provides:

• 🔐 Multi-tenant architecture with 12-level role hierarchy
• 📡 RADIUS integration for authentication and accounting
• 🌐 MikroTik RouterOS API integration for network management
• 📊 Real-time monitoring of sessions and bandwidth usage
• 💼 Comprehensive billing and customer management
• 🎨 Modern UI/UX with responsive design
• 🚀 100% feature complete (415/415 features implemented)

🛠️ Tech Stack

Technology	Version	Purpose
Laravel	12.x	Backend framework
PHP	8.2+	Programming language
MySQL	8.0	Application & RADIUS databases
Redis	Latest	Caching and queue management
Tailwind CSS	4.x	Frontend styling
Vite	7.x	Asset building
Docker	Latest	Containerized environment
Node.js	LTS	JavaScript runtime

🚀 Quick Start

Option 1: Automated Installation (Recommended)

For a fresh Ubuntu server (18.04+, 20.04+, 22.04+, or 24.04+):

# Download and run the installation script
wget https://raw.githubusercontent.com/i4edubd/ispsolution/main/install.sh
chmod +x install.sh
sudo bash install.sh

This script installs PHP, MySQL, Redis, Nginx, RADIUS, and configures everything automatically.

📖 Complete guide: INSTALLATION.md

Option 2: Docker Setup

# 1. Clone the repository
git clone https://github.com/i4edubd/ispsolution.git
cd ispsolution

# 2. Setup environment
cp .env.example .env

# 3. Start containers
make up

# 4. Install dependencies
make install

# 5. Setup application
docker-compose exec app php artisan key:generate
make migrate
make seed  # Optional: Load demo data

# 6. Access application
# → Application: http://localhost:8000
# → Mailpit: http://localhost:8025

Option 3: Manual Installation

Prerequisites: PHP 8.2+, Composer, Node.js, MySQL 8.0, Redis

# Install dependencies
composer install && npm install

# Setup environment
cp .env.example .env
php artisan key:generate

# Database setup
php artisan migrate

# Build assets
npm run build

# Start development server
php artisan serve

✨ Key Features

🎉 Major Milestone - January 2026

415/415 Features Complete (100%)

• ✅ 415 features implemented - All planned features delivered
• ✅ 100% production ready - Fully tested and documented
• ✅ Complete A-Z feature coverage - All functionality implemented
• 🎯 Production deployment ready

📄 See FEATURE_IMPLEMENTATION_STATUS.md | CHANGELOG.md

🆕 Latest Enhancements (January 31, 2026)

• ✅ Performance Optimizations

  • Package customer count caching (70% query reduction)
  • Cache warming command (php artisan cache:warm)
  • Database composite indexes for faster filtering
  • Query optimization and eager loading

• ✅ Reseller Features

  • Reseller signup and approval workflow
  • Parent-child account hierarchy
  • Commission tracking and reporting
  • Reseller dashboard and analytics

• ✅ Package Management

  • Package hierarchy with parent-child relationships
  • Package inheritance for easier management
  • Intelligent upgrade paths
  • Package comparison tools

• ✅ Multi-Language Support

  • English and Bengali translations
  • Language switcher in UI
  • Localized date formatting
  • Easy to add new languages

• ✅ Enhanced Customer Status

  • Overall status combining payment and service status
  • Improved filtering and reporting
  • Status-based dashboard widgets
  • Color-coded status badges

📖 Documentation:

• LOCALIZATION_GUIDE.md - Multi-language setup
• RESELLER_FEATURE_GUIDE.md - Reseller features
• PACKAGE_HIERARCHY_GUIDE.md - Package organization
• PERFORMANCE_OPTIMIZATION.md - Performance tips

📡 Network Services

• RADIUS Integration

  • FreeRADIUS authentication and accounting
  • User synchronization to RADIUS database
  • Support for RADIUS attributes (radcheck, radreply, radacct)
  • Session tracking and statistics

• MikroTik Management

  • PPPoE user management via RouterOS API
  • Real-time session monitoring
  • Remote session disconnection
  • Router health monitoring
  • Automatic retry on connection failure

• IPAM (IP Address Management)

  • IP pool and subnet creation
  • IP allocation and release
  • Allocation history tracking
  • Subnet overlap detection
  • Automatic cleanup of expired allocations

• Session Monitoring

  • Real-time active session tracking
  • Bandwidth usage monitoring
  • Connection history
  • Session statistics and reports

🎨 User Interface

• Modern admin interface based on Metronic Tailwind HTML
• Fully responsive design (desktop, tablet, mobile)
• Light and dark mode support
• Real-time monitoring dashboards
• Interactive IP allocation management
• Component-based architecture

🔐 Multi-Tenancy & Role System

The platform implements a comprehensive 12-role hierarchy with strict data isolation and permission-based access control.

Role Hierarchy

Level	Role	Access Scope	Can Manage
0	Developer	All tenants (supreme authority)	Super Admins
10	Super Admin	Own tenants only	Admins
20	Admin	Own ISP data	Operators, Sub-Operators, Staff
30	Operator	Own + sub-operator customers	Sub-Operators, Customers
40	Sub-Operator	Own customers only	Customers
50	Manager	Permission-based (view/edit)	None
70	Accountant	Financial data (view-only)	None
80	Staff	Permission-based (view/edit)	None
100	Customer	Self-service only	None

Data Isolation

• Developer: Access all tenants and data (system-wide authority)
• Super Admin: Only tenants they created
• Admin: Only data within their ISP tenant
• Operator: Own customers + sub-operator customers
• Sub-Operator: Only their own customers
• View-Only Roles: Permission-based read access within tenant

Quick Code Examples

// Check user role
if (auth()->user()->isDeveloper()) { /* ... */ }
if (auth()->user()->isAdmin()) { /* ... */ }

// Get accessible customers (automatically scoped by role)
$customers = auth()->user()->accessibleCustomers()->paginate(50);

// Check hierarchy permission
if (auth()->user()->canManage($otherUser)) { /* ... */ }

Demo Accounts

All demo accounts use password: password

Email	Role	Level
developer@ispbills.com	Developer	0
superadmin@ispbills.com	Super Admin	10
admin@ispbills.com	Admin	20
operator@ispbills.com	Operator	30
suboperator@ispbills.com	Sub-Operator	40
customer@ispbills.com	Customer	100

# Seed demo data
php artisan db:seed --class=DemoSeeder

# Seed roles
php artisan db:seed --class=RoleSeeder

📖 Documentation:

• ROLE_SYSTEM.md - Complete role system specification v3.1
• DATA_ISOLATION.md - Data isolation rules
• ROLES_AND_PERMISSIONS.md - Detailed permissions guide

⚙️ Configuration

Production Deployment

Build for production:

# Build optimized assets
npm run build

# Optimize Laravel
php artisan config:cache
php artisan route:cache
php artisan view:cache

# Optimize Composer autoloader
composer install --optimize-autoloader --no-dev

Production environment settings (.env):

APP_ENV=production
APP_DEBUG=false
APP_URL=https://yourdomain.com

# Strong database passwords
DB_PASSWORD=strong_random_password
RADIUS_DB_PASSWORD=strong_random_password

# MikroTik router configuration
MIKROTIK_HOST=your_router_ip
MIKROTIK_USERNAME=admin
MIKROTIK_PASSWORD=your_secure_password

# Enable HTTPS
SESSION_SECURE_COOKIE=true

Network Services

RADIUS Setup

Configure RADIUS database connection:

RADIUS_DB_HOST=radius-db
RADIUS_DB_DATABASE=radius
RADIUS_DB_USERNAME=radius
RADIUS_DB_PASSWORD=radius_secret
RADIUS_PASSWORD_HASH=cleartext  # Options: cleartext, md5, sha1

Capabilities:

• User authentication (radcheck table)
• Session accounting (radacct table)
• Automatic user synchronization
• RADIUS attributes support (radreply)

MikroTik Integration

Configure RouterOS API connection:

MIKROTIK_HOST=192.168.88.1
MIKROTIK_PORT=8728
MIKROTIK_USERNAME=admin
MIKROTIK_PASSWORD=your_password
MIKROTIK_TIMEOUT=10
MIKROTIK_RETRY_ATTEMPTS=3

Capabilities:

• PPPoE user management (add/update/remove)
• Active session listing
• Session disconnection
• Router health monitoring
• Automatic connection retry

IPAM Configuration

IP Address Management settings:

IPAM_DEFAULT_POOL_SIZE=254
IPAM_CLEANUP_DAYS=30
IPAM_ALLOCATION_TTL=86400
IPAM_ALLOW_OVERLAP=false

Capabilities:

• IP pool and subnet creation
• IP address allocation/release
• Allocation history tracking
• Subnet overlap detection
• Automatic cleanup of expired allocations

🔌 API Reference

IPAM API

GET    /api/v1/ipam/pools                 # List all IP pools
POST   /api/v1/ipam/pools                 # Create new pool
GET    /api/v1/ipam/subnets               # List all subnets
POST   /api/v1/ipam/subnets               # Create new subnet
GET    /api/v1/ipam/allocations           # List all allocations
POST   /api/v1/ipam/allocations           # Allocate IP address
DELETE /api/v1/ipam/allocations/{id}     # Release IP address

RADIUS API

POST   /api/v1/radius/authenticate        # Authenticate user
POST   /api/v1/radius/accounting/start    # Start accounting session
POST   /api/v1/radius/accounting/update   # Update session
POST   /api/v1/radius/accounting/stop     # Stop session
GET    /api/v1/radius/users/{user}/stats  # Get user statistics

MikroTik API

GET    /api/v1/mikrotik/sessions          # List active sessions
DELETE /api/v1/mikrotik/sessions/{id}     # Disconnect session
GET    /api/v1/mikrotik/profiles          # List PPPoE profiles
GET    /api/v1/mikrotik/health            # Health check

📖 Complete API documentation: docs/API.md

🛠️ Artisan Commands

IPAM Management

php artisan ipam:cleanup              # Clean up expired IP allocations
php artisan ipam:cleanup --days=30    # Clean up allocations older than 30 days
php artisan ipam:cleanup --force      # Skip confirmation prompt

RADIUS Management

php artisan radius:sync-user {userId}         # Sync user to RADIUS database
php artisan radius:sync-user 1 --password=newpass  # Sync with new password
php artisan radius:sync-users --status=active      # Sync all active users
php artisan radius:sync-users --force              # Force sync all users

MikroTik Management

php artisan mikrotik:health-check              # Check router connectivity
php artisan mikrotik:health-check --router=1   # Check specific router
php artisan mikrotik:health-check --verbose    # Detailed output
php artisan mikrotik:sync-sessions             # Sync active sessions
php artisan mikrotik:sync-sessions --router=1  # Sync specific router

Scheduled Tasks

The following tasks run automatically via Laravel's scheduler:

Task	Frequency	Description
IPAM Cleanup	Daily (midnight)	Remove expired IP allocations
RADIUS Sync	Every 5 minutes	Sync active users to RADIUS
Session Sync	Every minute	Sync sessions from MikroTik
Health Check	Every 15 minutes	Check MikroTik connectivity

Enable scheduler: Add to crontab:

* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

🧪 Testing & Development

Running Tests

# Run all tests
make test

# Run with coverage
make test-coverage

# Run specific test suite
docker-compose exec app php artisan test --testsuite=Feature

# Run specific test file
docker-compose exec app php artisan test tests/Feature/Services/IpamServiceTest.php

Development Workflow

make up                # Start containers
make shell             # Enter app container
npm run dev            # Watch for changes (hot reload)
make test              # Run tests
make lint              # Check code quality
make fix               # Fix code style issues

Code Quality

• PSR-12 Coding Standards: Use vendor/bin/pint to check/fix
• Static Analysis: Run vendor/bin/phpstan analyse
• Commit Format: Follow Conventional Commits

📖 Testing guide: docs/TESTING.md

🏗️ Architecture

Service Layer

Service-oriented architecture with contracts and implementations:

Contracts:

• app/Contracts/IpamServiceInterface.php - IP address management
• app/Contracts/RadiusServiceInterface.php - RADIUS operations
• app/Contracts/MikroTikServiceInterface.php - Router management

Implementations:

• app/Services/IpamService.php
• app/Services/RadiusService.php
• app/Services/MikroTikService.php

Database Schema

Application Database

Table	Purpose
users	System users
service_packages	Bandwidth packages
ip_pools	IP address pools
ip_subnets	Network subnets
ip_allocations	IP assignments
ip_allocation_histories	Allocation tracking
radius_sessions	Session cache

RADIUS Database

Table	Purpose
radcheck	User credentials
radreply	User attributes
radacct	Accounting records

Docker Services

Service	Description	Port
app	PHP 8.2-FPM application	-
nginx	Web server	8000
db	MySQL 8.0 (application)	3306
radius-db	MySQL 8.0 (RADIUS)	3307
redis	Caching and queues	6379
mailpit	Email testing	1025, 8025

🔧 Troubleshooting

Docker Issues

Containers won't start:

make down
docker system prune -f
make up

Database connection errors:

• Check containers: docker-compose ps
• Verify .env credentials
• Wait 30 seconds after startup for database initialization

Permission errors:

docker-compose exec app chown -R www:www /var/www/html/storage
docker-compose exec app chmod -R 755 /var/www/html/storage

MikroTik Connection Issues

If health check fails:

1. Verify router accessibility from Docker network
2. Enable API service on router
3. Check credentials in .env
4. Verify firewall allows port 8728

RADIUS Integration Issues

If authentication fails:

1. Check radius-db container is running
2. Verify RADIUS database migrations ran
3. Test sync: php artisan radius:sync-user 1
4. Confirm entries in radcheck table

📚 Documentation

Getting Started

• INSTALLATION.md - Complete automated installation guide
• ONBOARDING_ROUTER_CONFIGURATION_GUIDE.md - Complete onboarding & router configuration guide
• ONBOARDING_IMPLEMENTATION.md - Implementation details for onboarding features
• POST_DEPLOYMENT_STEPS.md - Essential post-deployment steps
• DOCUMENTATION_INDEX.md - Complete documentation index
• PROJECT_STATUS.md - Current status and roadmap

User Guides by Role

• Developer Guide - Level 0: System development
• Super Admin Guide - Level 10: Tenant management
• Admin Guide - Level 20: ISP operations
• Operator Guide - Level 30: Area management
• Sub-Operator Guide - Level 40: Local management
• Manager Guide - Level 50: Oversight
• Staff Guide - Level 80: Support
• Customer Guide - Level 100: Self-service

Technical Documentation

• API Documentation - Complete REST API reference
• Testing Guide - How to run and write tests
• ROLES_AND_PERMISSIONS.md - Role system details
• ROLE_SYSTEM.md - Complete specification v3.1
• DATA_ISOLATION.md - Data isolation rules
• MULTI_TENANCY_ISOLATION.md - Multi-tenancy architecture

Feature Documentation

• Network Services Guide - RADIUS, MikroTik, IPAM
• OLT Service Guide - OLT/ONU management
• FEATURE_IMPLEMENTATION_STATUS.md - Feature status
• PANELS_SPECIFICATION.md - Panel specifications

Phase 2 Features (NEW - 2026-01-29) ✨

• PHASE_2_FEATURES_USER_GUIDE.md - Complete user guide for new features
  • SMS Payment System - Purchase SMS credits with tiered pricing
  • Auto-Debit System - Automatic bill payments for customers
  • Subscription Payments - Platform billing management
  • Bkash Tokenization - One-click payments with saved methods
• PHASE_2_IMPLEMENTATION_STATUS.md - Detailed implementation progress (85% complete)
• IMPLEMENTATION_COMPLETE_SUMMARY.md - Executive summary and statistics
• REFERENCE_SYSTEM_QUICK_GUIDE.md - Original requirements and roadmap

MikroTik Integration

• ONBOARDING_ROUTER_CONFIGURATION_GUIDE.md - Complete router setup & configuration (Recommended)
• MIKROTIK_QUICKSTART.md - Quick start guide
• MIKROTIK_ADVANCED_FEATURES.md - Advanced features

Contributing

• CONTRIBUTING.md - Contribution guidelines
• CHANGELOG.md - Version history
• Changelog Guide - Commit message format

🤝 Contributing

We welcome contributions! Here's how to get started:

Quick Start

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit using Conventional Commits:

   git commit -m "feat(billing): add PayPal integration"

4. Push to your branch: git push origin feature/amazing-feature
5. Open a Pull Request

Commit Message Format

We use Conventional Commits for automatic changelog generation:

<type>(<scope>): <description>

Examples:
feat(auth): add two-factor authentication
fix(billing): resolve invoice calculation bug
docs: update API documentation

Types: feat, fix, docs, style, refactor, perf, test, chore

Code Quality Standards

Before committing:

• ✅ Run tests: make test or php artisan test
• ✅ Check style: vendor/bin/pint
• ✅ Run analysis: vendor/bin/phpstan analyse
• ✅ Write tests for new features
• ✅ Update documentation

Continuous Integration

All PRs are automatically tested:

• Test Workflow - PHP 8.2 and 8.3 unit/feature/integration tests
• Lint Workflow - PHPStan and Laravel Pint checks
• Integration Workflow - Full Docker environment testing
• Changelog Workflow - Automatic changelog generation

📖 Full guidelines: CONTRIBUTING.md | Changelog Guide

📄 License

This project is licensed under the MIT License.

💬 Support

Need help? Here's where to find it:

• 📖 Documentation Index - All available guides
• 📊 Implementation Status - Current progress
• 🔍 Troubleshooting - See section above
• 🐛 GitHub Issues - Report bugs
• 📚 Laravel Docs - Laravel 12 documentation

---

Documentation • Installation • Contributing • Changelog

Made with ❤️ by the ISP Solution team