# EZSCALE Billing Platform

Modern Laravel 12 billing and customer management platform replacing WHMCS for EZSCALE Hosting.

## Repository
- **GitHub**: git@github.com:EZSCALE/accounting.git
- **Branch Strategy**: Feature branches → `develop` → `main`

## Documentation Files

| File | Purpose | Lines |
|------|---------|-------|
| **CLAUDE.md** | Project instructions for AI assistance | ~70 |
| **PROJECT_DEVELOPMENT.md** | Complete architecture & development plan | ~600 |
| **TASKS.md** | Detailed task breakdown (13 phases) | ~400 |
| **FEATURES.md** | Feature specifications (35+ features) | ~1000 |
| **KASM_AND_MULTITENANCY.md** | Kasm Workspaces + Multi-Tenancy implementation | ~600 |
| **GETTING_STARTED.md** | Development setup guide | ~300 |
| **README.md** | This file - project overview | - |

## Quick Overview

### What We're Building
A comprehensive billing and service management platform for EZSCALE Hosting that handles:
- **Services**: VPS, Dedicated Servers, Web Hosting, Game Servers, **Kasm Workspaces**
- **Billing**: Stripe + PayPal + Crypto with multi-currency support
- **Provisioning**: Fully automated via VirtFusion, Pterodactyl, SynergyCP, Enhance APIs
- **Monitoring**: ElastiFlow bandwidth tracking, uptime monitoring, status page
- **Support**: Deep SupportPal integration with SSO
- **Admin**: Comprehensive analytics, MRR/ARR/churn tracking, full customer control

### Tech Stack
- **Framework**: Laravel 12 (PHP 8.2+)
- **Frontend**: Vue 3 + Inertia.js + Tailwind CSS
- **UI Theme**: Vuexy VueJS + Laravel Admin Dashboard Template
- **Database**: MySQL 8.x (multi-region replication, 15-min backups)
- **Cache/Queue**: Redis + Laravel Horizon
- **Payments**: Laravel Cashier Stripe v16 + srmklive/laravel-paypal
- **Auth**: Laravel Fortify + Passport (OAuth2/SSO)
- **Email**: Mailgun or SendGrid
- **Monitoring**: ElastiFlow (NetFlow/sFlow), built-in uptime checks
- **CI/CD**: GitHub Actions with staging environment
- **Security**: Cloudflare Zero Trust + 2FA/passkeys

### Domains
- **ezscale.cloud** — Marketing site, product catalog, public pages
- **account.ezscale.cloud** — Customer dashboard, service management
- **admin.ezscale.cloud** — Admin panel (Cloudflare Zero Trust protected)
- **status.ezscale.cloud** — Public status page

### Key Features
- ✅ Fully automated provisioning (VPS, Dedicated, Hosting, Game Servers)
- ✅ Multi-currency billing (USD, EUR, GBP, etc.)
- ✅ Advanced coupon system (stackable, geo-restricted, A/B testing)
- ✅ Automatic loyalty rewards (5-20% based on tenure)
- ✅ Self-service upgrades/downgrades with proration
- ✅ Bandwidth monitoring with auto-billing overages
- ✅ Team accounts with granular permissions
- ✅ Referral credit system
- ✅ Free trial support
- ✅ Comprehensive API with webhooks
- ✅ Built-in abuse management system
- ✅ Fraud detection and prevention
- ✅ Customer custom domains (CNAME support)
- ✅ Cryptocurrency payment support
- ✅ Exit surveys and win-back campaigns
- ✅ Real-time dashboard (WebSockets + polling)
- ✅ Multi-channel admin alerts (Discord, Email, SMS)
- ✅ GDPR-compliant data deletion
- ✅ Full audit trail and login history
- ✅ Unified communication timeline

## Current Status: Planning Phase

We are currently in the **documentation and planning phase**. This repository contains comprehensive planning documents but no code yet.

### Planning Complete ✓
- [x] Infrastructure architecture designed
- [x] Database schema defined
- [x] All integrations documented (6 external APIs)
- [x] Feature specifications written (35+ features)
- [x] Development phases outlined (11 phases)
- [x] Task breakdown completed (200+ tasks)
- [x] Security architecture defined
- [x] WHMCS migration strategy planned

### Next Steps
1. Review and approve planning documents
2. Set up development environment on separate machine
3. Initialize Laravel 12 project with Vue + Inertia
4. Begin Phase 1: Foundation (auth, database, core setup)

## Development Phases

| Phase | Focus | Status |
|-------|-------|--------|
| **Phase 1** | Foundation & Core Setup | Planned |
| **Phase 2** | Billing & Subscriptions | Planned |
| **Phase 3** | Provisioning Automation | Planned |
| **Phase 4** | Customer Dashboard | Planned |
| **Phase 5** | Admin Panel | Planned |
| **Phase 6** | Bandwidth Monitoring & Billing | Planned |
| **Phase 7** | SupportPal Integration | Planned |
| **Phase 8** | Marketing Frontend | Planned |
| **Phase 9** | RESTful API | Planned |
| **Phase 10** | Testing, Migration & Launch | Planned |
| **Phase 11** | Future Enhancements | Backlog |
| **Phase 12** | Kasm Workspaces Integration | Planned |
| **Phase 13** | Multi-Tenancy (Resellers) | Planned |

## Infrastructure Integration

### Service Provisioning
| Platform | Service Type | API | Automation |
|----------|-------------|-----|------------|
| **VirtFusion** | VPS | REST API | Fully automated |
| **Pterodactyl** | Game Servers | REST API | Fully automated |
| **SynergyCP** | Dedicated Servers | REST API | Automated (semi-auto for inventory) |
| **Enhance** | Web Hosting | REST API | Fully automated |

### Support & Monitoring
| System | Purpose | Integration |
|--------|---------|-------------|
| **SupportPal** | Ticketing | SSO + Full API integration |
| **ElastiFlow** | Bandwidth Monitoring | API queries for usage data |
| **Juniper Switches** | Network | NetFlow/sFlow exports |

### Payment Gateways
| Gateway | Usage | Integration |
|---------|-------|-------------|
| **Stripe** | Primary (~80%) | Laravel Cashier v16 |
| **PayPal** | Secondary (~20%) | srmklive/laravel-paypal |
| **Crypto** | Optional | Coinbase Commerce |

## Database Overview

### Core Tables
- **Users & Auth**: users, user_profiles, roles, permissions, audit_logs, login_history
- **Billing**: plans, subscriptions, invoices, payment_transactions, coupons, account_credits
- **Services**: services, provisioning_logs, bandwidth_usage, backups
- **Support**: support_tickets (mirrored), announcements
- **Team**: team_members, team_invitations
- **Monitoring**: uptime_checks, uptime_incidents, status_components
- **Abuse**: abuse_reports, abuse_actions
- **Communication**: customer_timeline, webhook_deliveries
- **Network**: ip_addresses, datacenters

See **PROJECT_DEVELOPMENT.md** for complete schema with all columns.

## WHMCS Migration

### Scope
- Full historical data migration (100-1000 customers)
- All invoices, payments, services, subscriptions
- Automated migration scripts (Laravel commands)
- 30-day parallel operation period
- Redirect old WHMCS URLs to new platform

### Migration Commands
```bash
php artisan migrate:whmcs-customers       # Import customers and profiles
php artisan migrate:whmcs-subscriptions   # Import active subscriptions
php artisan migrate:whmcs-invoices        # Import invoice history
php artisan migrate:whmcs-payments        # Import payment history
php artisan migrate:whmcs-services        # Import service configurations
php artisan migrate:whmcs-tickets         # Migrate tickets to SupportPal
```

## Security

### Authentication
- **Customer**: Email + password, optional 2FA (TOTP/passkeys)
- **Admin**: Email + password + required 2FA (passkeys preferred)
- **Admin Panel**: Behind Cloudflare Zero Trust access control
- **API**: Laravel Sanctum token authentication

### Data Protection
- Service credentials encrypted at rest
- HTTPS enforced everywhere
- CSRF protection on all forms
- Rate limiting on auth and API
- SQL injection prevention (Eloquent ORM)
- XSS prevention (Blade/Vue escaping + CSP)

### Compliance
- GDPR-compliant automated data deletion
- Full audit trail of admin actions
- Login history with IP tracking
- Fraud detection on signup
- Abuse management system

## Performance & Scalability

### Caching Strategy
- Real-time: Today's revenue, active orders
- 15-min cache: Historical analytics
- Daily aggregation: Month/year totals

### Queue System
- **Critical queue**: Provisioning, payments, suspension
- **Normal queue**: Emails, notifications, backups
- **Low queue**: Analytics, reports, cleanup

### Scaling
- Cloudflare CDN + WAF + DDoS protection
- Load balancer with auto-scaling
- Multi-region database replication
- 15-minute backup RPO

## API

### Customer API (Full Control)
- Create, modify, delete services
- View invoices and billing history
- Manage payment methods
- Check bandwidth usage
- Reboot/manage servers

### Webhook Support
- Customers can register webhook URLs
- Events: `invoice.created`, `service.provisioned`, `bandwidth.threshold_reached`, etc.
- HMAC signature verification
- Automatic retry on failure

### Custom Domains
- Customers can point `billing.theirdomain.com` to platform
- Auto-provisioned SSL via Let's Encrypt
- DNS verification required

## Analytics & Reporting

### Admin Dashboard
- MRR (Monthly Recurring Revenue)
- ARR (Annual Recurring Revenue)
- Churn rate and customer growth
- Revenue trends (daily, monthly, yearly)
- Popular plans and conversion rates
- Outstanding invoices

### Financial Reports
- Revenue reports (by period, service, plan)
- Profit & Loss statements
- Tax reports (sales tax, VAT)
- Aging reports (overdue invoices)
- Refund reports
- Subscription metrics

## Development Machine

**Important**: This machine is for documentation and planning only. The actual Laravel project will be built on a separate development machine.

## Contact

For questions about this project, contact the EZSCALE development team.

---

**Status**: Planning Phase - Documentation Complete
**Last Updated**: February 8, 2026
**Total Planning Documents**: 4 files, ~2000 lines of specifications