Extending Features

[lupael]

📘 SaaS ISP Platform — Merged Architecture

📐 Core Architecture Rules

• Framework: Laravel (PHP)
• Authentication: FreeRADIUS for AAA (Authentication, Authorization, Accounting)
• Network Integration: MikroTik routers via RouterOS API
• Database: Dual MySQL databases (application + FreeRADIUS)
• Multi-tenancy: All queries scoped by tenant_id
• Business Logic: Resides in app/Services/
• Controllers: Handle only request/response, never core logic

---

👥 Role Hierarchy (Standardized)

• Developer (Platform Owner)
• Super Admin (Platform Reseller)
• Admin (ISP Owner)
• Operator (Reseller)
• Sub-Operator
• Manager
• Staff
• Accountant
• Customer (Subscriber)

---

🔧 Core Entities

• Customer → single source of truth for RADIUS/MikroTik status
• Invoice → automated billing
• Payment → gateway + manual
• ServicePackage → bandwidth, quota, validity
• RechargeCard → prepaid top-ups
• Commission → reseller/agent earnings

---

📜 Naming Conventions

• Admin = ISP Owner
• Operator = Reseller
• Customer = Subscriber
• Consistent terminology across UI, docs, and code

---

🔄 Refactor Guidelines

• REST API cleanup → consolidate into app/Services/
• Role hierarchy standardization → purge unused roles
• MikroTik/NAS integration → merge into MikrotikService
• Gateway logic → standardize via reusable service methods
• Documentation → update Markdown checklists + ERD diagrams

---

🗑️ Deprecation Rules

• Replace network_users → Customer
• Drop network_user_id → use customer_id
• Remove legacy REST API endpoints
• Delete obsolete roles + DB fields (legacy_status, old_role_id)
• Do not remove existing features
• Views must follow:
  • ✅ resources/views/panels/*
  • ❌ No legacy paths (resources/views/developer, etc.)

---

🎨 Panel View Management

• Adding Views:
  • Blade templates under resources/views/panels/
  • RBAC middleware for tenant + role checks
  • Dynamic navigation menus
• Removing Views:
  • Identify unused templates
  • Remove routes/controllers
  • Clean up navigation links
  • Document in changelog

---

🔍 Duplicate Check Rules

• Customers → unique email, phone, username
• Invoices → unique invoice numbers per tenant
• Payments → prevent duplicate transaction IDs
• Sessions → disallow multiple active sessions per customer_id
• Recharge Cards → unique card codes, prevent reuse
• Panel Views → avoid duplicate menu entries

---

✅ Implementation Checklist

• Refactor legacy REST API endpoints
• Merge MikroTik/NAS infrastructure
• Add tenant scoping to all queries
• Unit tests for MikrotikService + OltService
• Update invoice generation logic
• Remove deprecated roles + DB fields
• Purge unused Blade templates
• Replace network_users with Customer
• Add/remove panel views with RBAC enforcement
• Implement duplicate checks

---

🌐 B2B2B Multi-Tenancy Model

• Developer (Platform Owner): sells SaaS subscriptions to Super Admins
• Super Admin (Platform Reseller): buys slots, resells to Admins (local ISPs)
• Admin (ISP Owner): buys slots, manages customers + infrastructure

1. Three-Level Database Hierarchy

| users | tenantsplatform_resellers | ispsbranches |

2. Parent Relationship (Migration Example)

Schema::table('users', function (Blueprint $table) {
    $table->unsignedBigInteger('parent_id')->nullable(); // Who created this user?
    $table->unsignedBigInteger('subscription_plan_id')->nullable();
    $table->timestamp('expires_at')->nullable(); // For Super Admin subscriptions
});

3. Subscription Logic (Middleware)

public function handle($request, $next)
{
    $user = $request->user();
    $superAdmin = ($user->role === 'Admin') ? User::find($user->parent_id) : $user;

    if ($superAdmin->role === 'Super Admin' && now()->gt($superAdmin->expires_at)) {
        return response()->view('errors.subscription_expired', [], 403);
    }

    return $next($request);
}

4. Billing Logic (Developer Revenue)

• Super Admins purchase slots via bKash/Nagad/Stripe/PayPal
• Payment updates expires_at + isp_limit
• Admins cannot operate if parent Super Admin subscription expired

---

🖥️ Panel Requirements

• Developer Panel: reseller lifecycle, slot management, impersonation, analytics, audit trail
• Super Admin Panel: ISP management, subscription enforcement, BI tools
• Customer Portal: real-time visibility, billing, bandwidth turbo, support

---

📑 Migration Notes

• Check GEMINI.md for architecture references
• Ensure all new panels follow resources/views/panels/* convention
• Document every refactor in Markdown checklists + changelog
• Update ERD diagrams to reflect new hierarchy + entity relationships