website/FEATURES.md

FEATURES.md - EZSCALE Site Feature Specifications

Overview

This document details all feature decisions made during planning. Reference this when building specific features.

---

1. Coupon & Discount System

Coupon Types

• Percentage discount (e.g., 20% off)
• Fixed amount (e.g., $10 off)
• Free trial extensions (e.g., extend trial by 7 days)

Advanced Restrictions

• Expiry dates
• Maximum uses (total and per customer)
• First purchase only
• Specific plans/services
• Minimum order value
• Recurring vs one-time discounts
• Stackable coupons (allow multiple coupons per order)
• User groups (coupons for specific customer segments)
• Geographic restrictions (US-only coupons, EU-only, etc.)
• A/B testing support (track conversion by coupon)

Database Schema Addition

coupons table:
├── stackable (boolean - can be combined with other coupons)
├── user_group (nullable - admin, vip, new_customer, etc.)
├── allowed_countries (JSON array - e.g., ["US", "CA", "GB"])
├── blocked_countries (JSON array)
├── conversion_tracking (boolean - track for analytics)
├── variant_id (nullable - for A/B testing)

---

2. Plan Changes & Billing

Upgrade/Downgrade Logic

• Immediate proration for plan changes
  • Calculate unused time credit on current plan
  • Apply credit to new plan price
  • Charge/credit difference immediately
  • Update service resources immediately (VirtFusion/Pterodactyl API calls)

Example Calculation

Customer on $10/month VPS (30 days), used 10 days
Upgrades to $20/month VPS

Credit: $10 * (20 days / 30 days) = $6.67
New charge: $20 - $6.67 = $13.33

Implementation Notes

• Use Laravel Cashier's swap() method for Stripe subscriptions
• For PayPal, manually calculate and create new subscription
• Queue API calls to update VPS resources
• Send confirmation email with proration details

---

3. Payment Retry & Dunning

Strategy

• Use Stripe Smart Retries (built-in dunning management)
• Stripe automatically retries failed payments with ML-optimized timing
• Laravel webhooks listen for payment failure events

Our Enhancement

• On payment failure event:
  • Send customer email with retry schedule
  • Add grace period (7 days) before suspension
  • Send reminder at 3 days before suspension
  • Suspend service if still unpaid
  • Discord webhook alert for high-value customer failures

Configuration

// config/billing.php
'dunning' => [
    'grace_period_days' => 7,
    'suspension_warning_days' => 3,
    'termination_days' => 30, // 30 days after suspension
],

---

4. Datacenter & Location Management

Per-Plan Location

• Plans are tied to specific datacenters
• Example: "VPS-Basic-US-East", "VPS-Basic-EU-West"
• Different pricing per location (if applicable)

Database Schema

plans table:
├── datacenter_location (string - us-east, us-west, eu-west, ap-southeast)
├── datacenter_code (string - NYC1, LAX2, AMS1, SG1)
├── location_display_name (string - "New York, USA")

datacenters table (new):
├── id
├── code (NYC1, LAX2, etc.)
├── name (New York - US East)
├── location (city, country)
├── available_services (JSON - ['vps', 'dedicated', 'hosting'])
├── status (active, maintenance, full)

VirtFusion Integration

• Each datacenter maps to a VirtFusion region/hypervisor group
• Provisioning service selects appropriate hypervisor based on plan's datacenter

---

5. Customer Onboarding

Guided Onboarding Flow

1. Email verification - Confirm email address
2. Profile completion - Company name, address (for tax calculations)
3. Payment method - Add credit card or PayPal
4. Plan selection - Choose service and datacenter
5. Service provisioning - Automated provisioning begins
6. Welcome tour - Brief overlay tour of dashboard features

Implementation

• Use Laravel Multi-Step Forms or similar
• Store progress in session
• Allow skipping steps (except email verification)
• Show progress bar: "Step 2 of 5"

Post-Onboarding

• Redirect to service provisioning status page
• Email: "Your VPS is being provisioned" (ETA: 5 minutes)
• Email: "Your VPS is ready!" (includes credentials, getting started guide)
• Dashboard widget: "Next steps" (upload SSH key, configure firewall, install software)

---

6. Loyalty Rewards Program

Automatic Tenure-Based Discounts

Tenure	Discount
1+ years	5% off recurring
2+ years	10% off recurring
3+ years	15% off recurring
5+ years	20% off recurring

Implementation

• Scheduled job runs monthly to update customer discount tiers
• Apply discount as automatic coupon on renewals
• Display loyalty badge in dashboard: "Loyal Customer - 5% Discount"
• Email notification when customer reaches new tier

Database Schema

users table additions:
├── customer_since (timestamp - first paid invoice date)
├── loyalty_tier (integer - 0, 1, 2, 3, 5 years)
├── loyalty_discount_percent (decimal - calculated discount)

---

7. Dedicated Server Waitlist

Notify When Available Approach

• Customer signs up for email notifications
• No payment or reservation
• When inventory available, send email blast to waitlist
• First-come, first-served checkout

Waitlist Features

• Show estimated wait time (based on average turnover)
• Let customer specify desired specs (RAM, CPU, disk)
• Email when exact match available
• Email when close match available

Database Schema

server_waitlist table:
├── id
├── user_id
├── plan_id (nullable - if waiting for specific plan)
├── desired_specs (JSON - RAM, CPU, disk requirements)
├── datacenter_preference (nullable)
├── notified_at (nullable - when we sent availability email)
├── status (waiting, notified, fulfilled, cancelled)
├── created_at, updated_at

---

8. Custom Pricing for Enterprise

Admin Custom Plan Creation

• Admin can create one-off plans for specific customers
• Set custom pricing, billing cycle, features
• Plan is private (not visible in public catalog)
• Assigned to specific customer only

Implementation

plans table additions:
├── visibility (public, private, archived)
├── assigned_user_id (nullable - for private plans)
├── is_custom (boolean - marked as custom pricing)

Admin UI

• Button: "Create Custom Plan for Customer"
• Form: Base on existing plan, modify price and features
• Auto-generate plan name: "Custom VPS - John Doe - $45/month"

---

9. GDPR Data Deletion

Automated Process

1. Customer requests deletion from account settings
2. System creates data deletion request (7-day waiting period)
3. Email confirmation: "Your account will be deleted in 7 days"
4. After 7 days, automated job runs:
   • Terminate all active services
   • Anonymize personal data (name → "Deleted User #12345")
   • Keep financial records (invoices, payments) with anonymized data
   • Delete: email, phone, address, notes, login history
   • Retain: subscription IDs, amounts, dates (for accounting/tax)
5. Email confirmation: "Your data has been deleted"

Database Schema

data_deletion_requests table:
├── id
├── user_id
├── requested_at
├── scheduled_for (requested_at + 7 days)
├── completed_at (nullable)
├── status (pending, processing, completed, cancelled)

Compliance

• Compliant with GDPR "right to be forgotten"
• Retain minimum data required by law (7 years for tax records)
• Provide data export (download all data as JSON/PDF) before deletion

---

10. Uptime Monitoring

Built-In Monitoring System

• Platform pings customer services every 5 minutes
• HTTP/HTTPS checks for web hosting
• ICMP ping for VPS/dedicated
• Game server query for Pterodactyl services

Features

• Uptime percentage displayed in dashboard
• Incident log (downtime events with duration)
• Customer can set up alert preferences (email, Discord webhook)
• Public status page shows overall platform health

Database Schema

uptime_checks table:
├── id
├── service_id
├── check_type (http, ping, game_query)
├── check_url_or_ip
├── status (up, down, degraded)
├── response_time_ms
├── checked_at

uptime_incidents table:
├── id
├── service_id
├── started_at
├── ended_at (nullable - ongoing)
├── duration_seconds
├── notified (boolean - customer was alerted)

---

11. Real-Time Dashboard Updates

Combination Approach

• Real-time (WebSockets) for:

  • New orders/subscriptions
  • Critical alerts (provisioning failures, payment failures)
  • Customer support tickets
  • Admin notifications

• Periodic refresh (polling) for:

  • Analytics charts (every 60 seconds)
  • Service status (every 30 seconds)
  • Bandwidth graphs (every 5 minutes)

Implementation

• Use Laravel Reverb (or Pusher) for WebSockets
• Channel: admin.{admin_id} for personal admin notifications
• Channel: customer.{user_id} for customer notifications
• Broadcast events: OrderCreated, ServiceProvisioned, PaymentFailed

---

12. Multi-Channel Admin Alerts

Alert Routing

Alert Type	Discord	Email	SMS (Twilio)
New order	✓	✗	✗
High-value order (>$500)	✓	✓	✓
Payment failure	✓	✗	✗
Provisioning failure	✓	✓	✓
System error	✓	✓	✗
Security alert (failed admin login)	✓	✓	✓
Service cancellation	✓	✗	✗

Configuration

// config/alerts.php
'channels' => [
    'discord' => env('DISCORD_WEBHOOK_URL'),
    'email' => env('ADMIN_ALERT_EMAIL'),
    'sms' => [
        'enabled' => env('SMS_ALERTS_ENABLED', false),
        'twilio_sid' => env('TWILIO_SID'),
        'twilio_token' => env('TWILIO_TOKEN'),
        'phone_numbers' => explode(',', env('ADMIN_PHONE_NUMBERS')),
    ],
],

---

13. Public Status Page

Built-In Status Page (status.ezscale.cloud)

• System Status: All systems operational / Degraded / Major outage

• Service Components:

  • VirtFusion API
  • Pterodactyl Panel
  • SynergyCP
  • Enhance
  • Billing System
  • Customer Portal
  • ElastiFlow (Bandwidth Monitoring)

• Incidents: Current and past incidents with updates

• Scheduled Maintenance: Upcoming maintenance windows

• Uptime Stats: 90-day uptime graph per component

Features

• Public page (no login required)
• RSS feed for status updates
• Customer can subscribe to status notifications
• Admin can post incidents and updates
• Auto-create incidents from monitoring (optional)

Database Schema

status_components table:
├── id
├── name (VirtFusion API, Billing System, etc.)
├── status (operational, degraded, outage)
├── description
├── group (Infrastructure, Billing, Control Panels)
├── sort_order

status_incidents table:
├── id
├── title
├── description
├── status (investigating, identified, monitoring, resolved)
├── severity (minor, major, critical)
├── affected_components (JSON array of component IDs)
├── started_at
├── resolved_at (nullable)

status_updates table:
├── id
├── incident_id
├── message
├── status_change (investigating → identified)
├── posted_at

---

14. Abuse Management System

Full Abuse Management Module

• Dedicated abuse ticket queue (separate from support)
• Abuse report submission form (public, for reporting abuse)
• Automated abuse detection (optional - DMCA API, spam blacklist checks)
• Service auto-suspension for severe abuse (CSAM, phishing)

Abuse Workflow

1. Abuse report received (email, web form, API)
2. Create abuse ticket (high priority)
3. Notify admin via Discord + email
4. Admin investigates, views customer history
5. Options:
   • Warn customer (send abuse notice email)
   • Suspend service immediately
   • Request content removal (give customer X hours)
   • Terminate account (severe violations)
6. Track abuse history per customer
7. Escalate repeat offenders automatically

Database Schema

abuse_reports table:
├── id
├── service_id (nullable - may not know which service yet)
├── user_id (nullable - determined after investigation)
├── reporter_email
├── reporter_name (nullable)
├── abuse_type (spam, copyright, phishing, illegal_content, other)
├── description
├── evidence (JSON - URLs, headers, attachments)
├── status (new, investigating, resolved, dismissed)
├── assigned_admin_id (nullable)
├── resolved_at (nullable)

abuse_actions table:
├── id
├── abuse_report_id
├── action_type (warning, suspension, termination, content_removal)
├── taken_by_admin_id
├── notes
├── created_at

customer_abuse_history:
├── user_id
├── total_reports
├── resolved_reports
├── warnings_sent
├── suspensions
├── risk_score (calculated - higher score = more likely to abuse)

---

15. Fraud Detection

Automated Fraud Scoring

• Check on signup/checkout before provisioning
• Assign risk score 0-100
• Auto-reject if score > 90
• Flag for manual review if score 50-90
• Auto-approve if score < 50

Fraud Signals

• Email: Disposable email domains (mailinator, guerrilla mail), newly created Gmail/Outlook
• IP Address: VPN/proxy detection, high-risk countries, IP mismatch with billing address
• Payment: Prepaid cards, multiple failed attempts, card BIN country mismatch
• Behavioral: New account placing large order, unusual order patterns
• Velocity: Multiple accounts from same IP in short time

Third-Party Services

• MaxMind MinFraud - IP and transaction risk scoring
• Stripe Radar - Built-in fraud detection
• Email verification API - Validate email deliverability

Implementation

// app/Services/Fraud/FraudDetectionService.php
public function calculateRiskScore(User $user, Order $order): int
{
    $score = 0;

    // Disposable email +30
    if ($this->isDisposableEmail($user->email)) $score += 30;

    // VPN/proxy +20
    if ($this->isVpnOrProxy($user->ip_address)) $score += 20;

    // High-risk country +15
    if ($this->isHighRiskCountry($user->country)) $score += 15;

    // ... more checks

    return min($score, 100);
}

---

16. Game Server Templates

Template Library

• Pre-configured templates for popular games
• One-click deployment from customer dashboard
• Admin can create/manage custom templates

Supported Games (Initial)

• Minecraft (Vanilla, Spigot, Paper, Forge, Fabric)
• ARK: Survival Evolved
• Rust
• Counter-Strike 2
• Palworld
• Valheim
• Terraria
• 7 Days to Die
• Team Fortress 2
• Garry's Mod

Template Features

• Default server configuration
• Recommended plugins/mods
• Startup parameters
• Port configurations
• Resource requirements (min RAM, CPU)

Database Schema

game_templates table:
├── id
├── game_name (Minecraft, ARK, etc.)
├── template_name (Vanilla 1.20, Spigot, etc.)
├── pterodactyl_egg_id
├── description
├── icon_url
├── default_config (JSON - startup params, server.properties, etc.)
├── min_ram_mb
├── recommended_ram_mb
├── min_cpu_cores
├── status (active, deprecated)
├── sort_order

---

17. Backups (Included in Plans)

Backup Features

• Daily automated backups for VPS/hosting
• Retention: 7 daily, 4 weekly, 3 monthly
• Customer can restore from dashboard (self-service)
• Backups stored on separate infrastructure (not same as service)

Backup Storage

• Use S3-compatible storage (Wasabi, Backblaze B2, MinIO)
• Encrypted backups
• Compression to save space

Implementation

• VirtFusion API: backup VPS snapshots
• Enhance API: backup hosting accounts
• Pterodactyl: backup game server files (via API or direct)
• SynergyCP: backup dedicated server config (customer responsible for data)

Database Schema

backups table:
├── id
├── service_id
├── backup_type (daily, weekly, monthly, manual)
├── size_bytes
├── storage_path (S3 URL or path)
├── status (pending, completed, failed, restoring)
├── created_at
├── expires_at (based on retention policy)

backup_restores table:
├── id
├── backup_id
├── service_id
├── requested_by_user_id
├── status (pending, in_progress, completed, failed)
├── created_at

---

18. Platform Backups

15-Minute RPO (Recovery Point Objective)

• MySQL binary logs replicated in real-time
• Transaction log backups every 15 minutes
• Full database backup daily
• Test restores weekly (automated)

Multi-Region Replication

• Master database in primary datacenter
• Read replica in secondary datacenter (async replication)
• Automatic failover to replica if master fails

Backup Retention

• 15-minute transaction logs: 7 days
• Daily full backups: 30 days
• Weekly full backups: 90 days
• Monthly backups: 1 year

Implementation

• Use MySQL Enterprise Backup or Percona XtraBackup
• Store backups in S3 with versioning enabled
• Encrypt backups at rest (AES-256)

---

19. IPv4 + IPv6 Dual-Stack

IP Allocation

• All VPS and dedicated servers get:

  • 1x IPv4 address (included)
  • /64 IPv6 subnet (included)

• Web hosting:

  • Shared IPv4 (multiple sites per IP)
  • Shared IPv6

• Game servers:

  • 1x IPv4 (included)
  • IPv6 optional (most game clients don't support)

Additional IPv4 Addresses

• Customer requests additional IPs via ticket
• Must provide justification (SSL certificates, multiple services, etc.)
• Admin reviews and approves
• Pricing: $3-5/month per additional IPv4

IPAM (IP Address Management)

• Track IP allocation in database
• Prevent duplicate assignments
• RDNS (reverse DNS) management
• SWIP (Shared Whois Project) for larger allocations

Database Schema

ip_addresses table:
├── id
├── ip_address (IPv4 or IPv6)
├── ip_version (4 or 6)
├── type (dedicated, shared)
├── service_id (nullable)
├── datacenter_id
├── status (available, allocated, reserved)
├── rdns_hostname (nullable)
├── notes

ip_requests table:
├── id
├── user_id
├── service_id
├── ip_version (4 or 6)
├── quantity
├── justification
├── status (pending, approved, rejected)
├── reviewed_by_admin_id
├── created_at

---

20. Invoice Numbering

Sequential Format: INV-000001

• Simple incrementing counter
• Never resets
• Starts at INV-000001
• Auto-increments for each invoice
• Zero-padded to 6 digits

Implementation

// Generate next invoice number
$lastInvoiceNumber = DB::table('invoices')
    ->orderBy('number', 'desc')
    ->value('number');

$nextNumber = $lastInvoiceNumber
    ? intval(substr($lastInvoiceNumber, 4)) + 1
    : 1;

$invoiceNumber = 'INV-' . str_pad($nextNumber, 6, '0', STR_PAD_LEFT);
// Result: INV-000001, INV-000002, ..., INV-123456

Database

invoices table:
├── number (unique, indexed - INV-000001)
├── stripe_invoice_id (nullable - for Stripe invoices)
├── paypal_invoice_id (nullable - for PayPal)

---

21. Team Accounts & Sub-Users

Full Team Support

• Primary account owner (billing access)
• Add team members with granular permissions
• Each team member gets own login (separate email)

Permission Levels

Permission	Description
Owner	Full access (billing, services, team management)
Billing Manager	View and pay invoices, manage payment methods
Technical Admin	Manage services (reboot, reinstall, view credentials)
Read-Only	View services and billing, no modifications
Custom	Admin defines specific permissions

Features

• Owner can invite team members via email
• Team members accept invitation, create account
• Audit log shows which team member performed actions
• Owner can revoke access anytime

Database Schema

team_members table:
├── id
├── account_owner_id (references users.id)
├── team_member_user_id (references users.id)
├── role (owner, billing_manager, technical_admin, read_only, custom)
├── permissions (JSON - for custom roles)
├── invited_at
├── accepted_at (nullable)
├── status (invited, active, revoked)

team_invitations table:
├── id
├── account_owner_id
├── email
├── role
├── token (unique invitation token)
├── expires_at
├── accepted_at (nullable)

---

22. Referral Credits

Referral Program

• Customer gets unique referral link: ezscale.cloud/ref/ABC123
• When referred friend signs up and pays first invoice:
  • Referrer gets $10 account credit
  • New customer gets $5 account credit
• Credits apply to future invoices automatically

Tracking

• Referral link parameter stored in session/cookie
• When customer registers, store referrer ID
• When first invoice paid, trigger credit issuance event

Database Schema

referrals table:
├── id
├── referrer_user_id
├── referred_user_id
├── referral_code (unique - ABC123)
├── status (pending, completed, credited)
├── credit_amount_referrer
├── credit_amount_referred
├── referred_at
├── first_payment_at (nullable)
├── credited_at (nullable)

account_credits table:
├── id
├── user_id
├── amount
├── source (referral, loyalty, admin_granted, promotional)
├── description
├── applied_to_invoice_id (nullable)
├── expires_at (nullable - credits can expire)
├── created_at

---

23. Free Trial System

Free Trial Configuration

• Trial length: 7 days (configurable per plan)
• Requires payment method (but not charged)
• Full service access during trial
• Auto-convert to paid subscription after trial ends
• Customer can cancel during trial (no charge)

Trial Limitations (Optional)

• Email verification required
• One trial per email address
• Fraud score check (reject high-risk trials)

Implementation

• Use Stripe's built-in trial period functionality
• For PayPal: create subscription with trial period
• Email reminders:
  • Day 1: Welcome email with getting started guide
  • Day 5: "2 days left in your trial"
  • Day 7: "Your trial has ended, subscription starts today"

Database Tracking

subscriptions table additions:
├── trial_ends_at (nullable - Cashier provides this)
├── trial_converted_at (nullable - when trial became paid)
├── trial_cancelled (boolean - cancelled during trial)

---

24. Chatbot for Marketing Site

Chatbot Features (Crisp, Tidio, or custom)

• Appears on ezscale.cloud (marketing site)
• Answers common questions:
  • Pricing
  • Service features
  • Datacenter locations
  • Billing questions
  • Signup process

Bot Flows

• Initial greeting: "Hi! How can I help you today?"
• Quick reply buttons: "Pricing", "Features", "Sign Up", "Talk to Human"
• If "Talk to Human": Create support ticket or offer callback

Integration

• Use Crisp or similar (GDPR-compliant, affordable)
• Escalate to human support via SupportPal ticket API
• Track chatbot interactions in analytics

---

25. Comprehensive Financial Reports

Reports Needed

1. Revenue Report

   • Total revenue by period (daily, monthly, yearly)
   • Breakdown by service type (VPS, Dedicated, Hosting, Game)
   • Breakdown by plan
   • Growth percentage vs previous period

2. Profit & Loss Statement

   • Revenue
   • Refunds
   • Payment gateway fees (Stripe, PayPal)
   • Infrastructure costs (VirtFusion, Pterodactyl, etc.)
   • Net profit

3. Tax Report

   • Sales tax collected by region
   • VAT collected (if applicable)
   • Export for accountant (CSV, PDF)

4. Aging Report

   • Outstanding invoices by age (0-30 days, 30-60, 60-90, 90+)
   • Total amount overdue
   • Customer list with overdue amounts

5. Refund Report

   • All refunds issued
   • Reason for refund
   • Total refunded by period

6. Subscription Report

   • New subscriptions this period
   • Cancelled subscriptions
   • Churn rate %
   • MRR and ARR

Export Formats

• PDF (formatted reports)
• CSV (raw data for Excel)
• JSON (API access)

Scheduled Reports

• Admin can schedule email delivery (weekly/monthly)
• Auto-send month-end reports to accounting team

---

26. Login History & Security Audit

Full Audit Trail

• Track all customer and admin logins
• Log IP address, device type, user agent, location (GeoIP)
• Customer can view their own login history
• Admin can view any user's login history

Security Features

• Alert on login from new device/location
• Alert on multiple failed login attempts
• Option to enable "trusted devices" (require 2FA on new devices only)
• Admin can force logout all sessions

Database Schema

login_history table:
├── id
├── user_id
├── ip_address
├── user_agent
├── device_type (desktop, mobile, tablet)
├── browser (Chrome, Firefox, Safari, etc.)
├── location_country
├── location_city (from GeoIP)
├── success (boolean - failed vs successful)
├── two_factor_used (boolean)
├── created_at

active_sessions table:
├── id
├── user_id
├── session_id (Laravel session ID)
├── ip_address
├── user_agent
├── last_activity_at
├── created_at

---

27. Invoice Consolidation

Customer Preference

• Customer can choose in account settings:
  • Consolidated: One invoice per billing cycle with all services
  • Separate: Each service gets its own invoice

Implementation

• Default: Consolidated
• Setting stored in user preferences
• Billing job checks preference before generating invoices
• For consolidated: Group by billing date, create single invoice with line items

Example Consolidated Invoice

INVOICE #INV-001234
Due Date: February 15, 2026

Line Items:
- VPS Pro - us-east (Feb 15 - Mar 15)    $20.00
- Web Hosting Basic (Feb 15 - Mar 15)    $10.00
- Game Server - Minecraft (Feb 15 - Mar 15) $15.00

Subtotal: $45.00
Tax (8%): $3.60
Total: $48.60

---

28. Unified Communication Timeline

Timeline View (Customer & Admin)

• Shows all interactions with customer in chronological order
• Event types:
  • Account created
  • Service provisioned
  • Invoice generated
  • Payment received
  • Email sent (with subject)
  • Support ticket created
  • Ticket reply
  • Service suspended
  • Service resumed
  • Login activity
  • Admin notes
  • Service upgrade/downgrade

Features

• Filter by event type
• Search timeline
• Admin can add manual notes
• Export timeline as PDF (for records)

Database Schema

customer_timeline table:
├── id
├── user_id
├── event_type (account_created, invoice_generated, etc.)
├── event_description
├── related_model_type (Invoice, Service, Ticket, etc.)
├── related_model_id
├── metadata (JSON - full event data)
├── created_by_admin_id (nullable - for admin notes)
├── created_at

---

29. API Features

Full Control API

• Customers can create, modify, delete services via API
• Same capabilities as dashboard
• RESTful design
• Sanctum token authentication

Webhook System

• Customers can register webhook URLs
• Events trigger POST requests to customer's webhook
• Events:
  • invoice.created
  • invoice.paid
  • service.provisioned
  • service.suspended
  • service.terminated
  • bandwidth.threshold_reached

Webhook Security

• HMAC signature for verification
• Retry failed webhooks (3 attempts)
• Webhook delivery log

Custom Domains (CNAME)

• Customer can point billing.theirdomain.com to account.ezscale.cloud
• SSL certificate auto-provisioned via Let's Encrypt
• Requires DNS verification (add TXT record)

Database Schema

api_tokens table (Sanctum provides):
├── id
├── tokenable_type
├── tokenable_id
├── name
├── token (hashed)
├── abilities (JSON - permissions)
├── last_used_at
├── created_at

customer_webhooks table:
├── id
├── user_id
├── url
├── events (JSON array - subscribed events)
├── secret (for HMAC signature)
├── status (active, disabled)
├── created_at

webhook_deliveries table:
├── id
├── webhook_id
├── event_type
├── payload (JSON)
├── response_code
├── response_body
├── attempts
├── delivered_at
├── created_at

custom_domains table:
├── id
├── user_id
├── domain (billing.theirdomain.com)
├── verification_token
├── verified_at
├── ssl_status (pending, active, failed)
├── created_at

---

30. VPS & Service Management

VPS Self-Service Reinstall

• Customer can reinstall OS from dashboard
• Choose from available OS templates
• Warning: "This will erase all data"
• Require confirmation (type service name)
• Queue reinstall job → VirtFusion API

Additional IP Requests

• Customer submits form with justification
• Admin reviews in admin panel
• Approve/reject with reason
• If approved: Assign IP from pool, add to invoice

DNS Integration

• Integrate with Cloudflare API for DNS management
• Customer adds Cloudflare API token in settings
• Auto-create DNS records when services provisioned
• A record for VPS: vps1.customer.com → 1.2.3.4
• A record for hosting: www.customer.com → hosting IP

---

31. Email Preferences & Notifications

Granular Email Control

Customer can toggle each notification type:

• ✓ Invoices (required)
• ✓ Payment receipts (required)
• ☐ Renewal reminders
• ☐ Service provisioned
• ☐ Bandwidth alerts
• ☐ Marketing emails
• ☐ Product updates
• ☐ Platform news

Renewal Reminder Schedule

• 30 days before renewal
• 14 days before renewal
• 7 days before renewal
• 1 day before renewal

Invoice Emails: Summary + PDF

Subject: Invoice #INV-001234 - $48.60 Due

Hi John,

Your invoice is ready:

Invoice #: INV-001234
Amount Due: $48.60
Due Date: Feb 15, 2026

Services:
- VPS Pro ($20.00)
- Web Hosting ($10.00)
- Game Server ($15.00)

View invoice: https://account.ezscale.cloud/invoices/001234
Download PDF: [attached]

Payment will be automatically charged on Feb 15.

---

32. Performance & Scalability

Analytics Dashboard: Hybrid Approach

• Real-time: Today's revenue, active orders
• Cached: Historical charts (updated every 15 min)
• Daily aggregation: Month/year totals (updated nightly)

Queue Configuration

• Critical queue (priority: high)

  • Service provisioning
  • Payment processing
  • Account suspension

• Normal queue (priority: medium)

  • Emails
  • Notifications
  • Backup jobs

• Low queue (priority: low)

  • Analytics aggregation
  • Report generation
  • Cleanup jobs

Laravel Horizon

• Monitor queue health
• Failed job tracking
• Retry failed jobs
• Queue metrics dashboard

Auto-Scaling Strategy

• Cloudflare CDN + WAF for DDoS protection
• Load balancer in front of app servers
• Auto-scale based on CPU/memory usage
• Scale up during traffic spikes (sales, launches)
• Scale down during low-traffic periods

---

33. Provisioning API Failure Handling

Queue and Retry Strategy

1. Customer completes checkout, payment succeeds
2. Provisioning job added to queue
3. Attempt to provision via API (VirtFusion, Pterodactyl, etc.)
4. If API fails:
   • Log error
   • Send Discord alert to admin
   • Email customer: "Service provisioning in progress, may take longer than usual"
   • Retry after 5 minutes
   • Retry after 15 minutes
   • Retry after 30 minutes
   • If still failing after 3 retries:
     • Create high-priority admin ticket
     • Email customer: "Provisioning delayed, our team is investigating"
     • Manual admin intervention required

Database Schema

provisioning_logs additions:
├── retry_count (integer - how many retries)
├── next_retry_at (nullable - scheduled retry time)
├── error_details (JSON - full error response)

---

34. Cryptocurrency Payments

Integration via Coinbase Commerce or BTCPay

• Add "Pay with Crypto" option at checkout
• Supported coins: Bitcoin, Ethereum, USDC, USDT
• Customer selects crypto, invoice generated
• Payment detected via webhook
• Auto-convert to USD for accounting

Implementation Notes

• Crypto payments are one-time (not recurring subscriptions)
• Customer must manually pay each invoice with crypto
• Or: Hold credit balance (customer pre-pays in crypto, drawn down monthly)

Database Schema

crypto_payments table:
├── id
├── invoice_id
├── user_id
├── provider (coinbase_commerce, btcpay)
├── crypto_currency (BTC, ETH, USDC)
├── crypto_amount
├── usd_amount
├── wallet_address (where customer sent payment)
├── transaction_hash (blockchain tx)
├── status (pending, confirmed, expired)
├── confirmed_at
├── created_at

---

35. Churn Prevention: Exit Survey + Win-Back

Exit Survey on Cancellation

• Modal appears when customer cancels subscription
• Questions:
  • "Why are you cancelling?" (multiple choice + other)
    • Too expensive
    • Switching to competitor
    • No longer need service
    • Technical issues
    • Poor support
    • Other (text field)
  • "What could we do better?" (optional text)
  • "Would you consider returning?" (Yes / Maybe / No)

Win-Back Email Campaign

• Triggered 30 days after cancellation
• Email sequence:
  • Day 30: "We miss you! Here's 20% off to come back"
  • Day 45: "Customer spotlight - see what you're missing"
  • Day 60: "Final offer: 30% off for 3 months"
• Stop sending if customer re-subscribes

Database Schema

cancellation_surveys table:
├── id
├── user_id
├── subscription_id
├── cancellation_reason
├── cancellation_feedback
├── would_return (yes, maybe, no)
├── created_at

win_back_campaigns table:
├── id
├── user_id
├── subscription_id (cancelled subscription)
├── campaign_started_at
├── emails_sent (integer)
├── last_email_sent_at
├── status (active, completed, unsubscribed, reactivated)

---

Summary

This comprehensive feature specification covers all aspects discussed during planning:

• ✅ Advanced coupon system with A/B testing
• ✅ Immediate proration for plan changes
• ✅ Stripe Smart Retries with grace periods
• ✅ Per-plan datacenter locations
• ✅ Guided customer onboarding
• ✅ Automatic loyalty rewards program
• ✅ Dedicated server waitlist system
• ✅ Custom enterprise pricing
• ✅ GDPR-compliant automated data deletion
• ✅ Built-in uptime monitoring
• ✅ Real-time dashboard (WebSockets + polling)
• ✅ Multi-channel admin alerts (Discord, Email, SMS)
• ✅ Public status page
• ✅ Full abuse management system
• ✅ Automated fraud detection
• ✅ Game server template library
• ✅ Backups included in plans (7/4/3 retention)
• ✅ 15-minute database backups with multi-region replication
• ✅ IPv4 + IPv6 dual-stack
• ✅ Sequential invoice numbering (INV-000001)
• ✅ Full team accounts with granular permissions
• ✅ Referral credit system
• ✅ Free trial periods
• ✅ Marketing chatbot
• ✅ Comprehensive financial reports
• ✅ Login history and security audit trail
• ✅ Customer choice: consolidated or separate invoices
• ✅ Unified communication timeline
• ✅ Full-control customer API with webhooks
• ✅ Custom domain support (CNAME)
• ✅ VPS self-service OS reinstall
• ✅ Additional IP address requests
• ✅ DNS integration (Cloudflare)
• ✅ Granular email preferences
• ✅ Multiple renewal reminders
• ✅ Hybrid analytics (real-time + cached)
• ✅ Multi-queue system with Laravel Horizon
• ✅ Auto-scaling for traffic spikes
• ✅ Provisioning API failure queue-and-retry
• ✅ Cryptocurrency payment support
• ✅ Exit survey and win-back campaigns

All features documented and ready for implementation!