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
```sql
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
```php
// 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
```sql
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
```sql
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
```sql
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
```sql
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
```sql
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
```sql
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
```php
// 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
```sql
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
```sql
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
```php
// 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
```sql
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
```sql
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
```sql
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
```php
// 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
```sql
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
```sql
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
```sql
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
```sql
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
```sql
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
```sql
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
```sql
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
```sql
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
```sql
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
```sql
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!**