Extending Features

[lupael]

---

📘 SaaS ISP Platform

📐 Core Architecture Rules

• Framework: Laravel 10+ with PHP 8.2
• Multi-tenancy: All queries must be scoped by tenant_id.
• Business Logic: Resides in app/Services/.
• Controllers: Handle only request/response, never core logic.

---

👥 Role Hierarchy (Standardized)

1. Developer (Platform Owner)
2. Super Admin (Platform Reseller)
3. Admin (ISP Owner)
4. Operator (Reseller)
5. Sub-Operator
6. Manager
7. Staff
8. Accountant
9. 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: Remove deprecated endpoints, consolidate logic into app/Services/.
• Role Hierarchy Standardization: Map legacy roles to new hierarchy, purge unused roles.
• MikroTik/NAS Integration: Merge duplicated connection logic into MikrotikService.
• Gateway Logic: Standardize payment gateway handling via reusable service methods.
• Documentation: Update Markdown checklists and ERD diagrams after each refactor.

---

🗑️ Deprecation Rules

• Replace network_users with Customer.
• Drop network_user_id → use customer_id.
• Remove legacy REST API endpoints.
• Delete obsolete roles and DB fields (legacy_status, old_role_id).
• Do not remove existing features.
• Do not use old view paths:
  • ❌ resources/views/developer
  • ❌ resources/views/super-admin
  • ❌ resources/views/admin
• ✅ All panels must include existing views under:
  • resources/views/panels/developer
  • resources/views/panels/super-admin
  • resources/views/panels/admin
  • resources/views/panels/operator
  • resources/views/panels/sub-operator
  • resources/views/panels/customer

---

🎨 Panel View Management

• Adding Views:

  • Create Blade templates under resources/views/panels/.
  • Apply RBAC middleware for tenant + role checks.
  • Update navigation menus dynamically.

• Removing Views:

  • Identify unused templates.
  • Remove associated routes/controllers.
  • Clean up navigation links.
  • Document removal in changelog.

---

🔍 Duplicate Check Rules

• Customer: 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.
• Write unit tests for MikrotikService and OltService.
• Update invoice generation logic.
• Remove deprecated roles and DB fields.
• Purge unused Blade templates.
• Replace network_users with Customer.
• Add/remove panel views with RBAC enforcement.
• Implement duplicate checks for customers, invoices, sessions, recharge cards.

---

🌐 B2B2B Multi-Tenancy Model

This platform now operates as a Business-to-Business-to-Business (B2B2B) SaaS model:

• Developer (Platform Owner): Sells SaaS subscriptions to Super Admins.
• Super Admin (Platform Reseller): Buys slots from Developer, resells them to Admins (local ISPs).
• Admin (ISP Owner): Buys slots from Super Admin, manages customers and infrastructure.

---

1. Three-Level Database Hierarchy

Level	Table	Key Responsibility
Owner (You)	users (Role: Developer)	Manages Super Admin subscriptions and platform updates.
Super Admin	tenants / platform_resellers	Buys subscription from Developer, creates Admin slots.
Admin	isps / branches	Buys slot from Super Admin, manages customers/MikroTik.

---

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)

app/Http/Middleware/CheckSubscription.php

public function handle($request, $next)
{
    $user = $request->user();
    
    // If Admin, check their parent Super Admin
    $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 and isp_limit.
• Admins cannot operate if their parent Super Admin subscription is expired.

---

🖥️ Panel Requirements

Developer (Owner) Panel

• Platform Reseller Lifecycle
• Slot Management
• Impersonation Engine
• Global Revenue Analytics
• System Audit Trail

Super Admin (Platform Reseller) Panel

• ISP Management
• Subscription Enforcement
• Business Intelligence

Customer (Subscriber) Portal

• Real-time Visibility
• Billing Management
• Bandwidth Turbo
• Support System

---

📑 Migration Notes

• Check GEMINI.md for existing 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.

---

This Markdown version now **explicitly enforces that all panels must include existing views under `resources/views/panels/*`** and integrates the **B2B2B SaaS model with three-tier multi-tenancy**.