0fe4e4ab42
Update CLAUDE.md with mandatory phase tracking rules (GitHub issues + TASKS.md), TypeScript requirement for all frontend code, Vuexy theme reference, and updated project structure reflecting Phase 1-2 completion. Add comprehensive CLAUDE.md to Vuexy theme directory documenting components, patterns, and conventions. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
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 | ~80 |
| 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 |
| ADVANCED_FEATURES.md | Advanced feature specifications (28 features) | ~1400 |
| IDEAS.md | Future feature ideas and exploration topics | ~500 |
| README.md | This file - project overview | - |
| website/ | Laravel 12 base installation | - |
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: Base Install Complete
The Laravel 12 base installation exists in the website/ directory. Planning and documentation is complete. No additional packages or customizations have been added yet.
Planning Complete ✓
- Infrastructure architecture designed
- Database schema defined
- All integrations documented (6 external APIs)
- Feature specifications written (35+ features)
- Development phases outlined (11 phases)
- Task breakdown completed (200+ tasks)
- Security architecture defined
- WHMCS migration strategy planned
- Laravel 12 base install created (
website/)
Next Steps
- Install core dependencies (Cashier, Fortify, Passport, PayPal, Spatie)
- Configure environment and database
- Create database schema and migrations
- 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
Run from the website/ directory:
cd website
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.comto 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
Project Layout
The Laravel 12 application is located in the website/ directory (base install, no additional packages yet). Documentation and planning files are in the repository root.
Important: This machine is for documentation and planning only. The actual project building and code execution happens on a separate development machine.
Contact
For questions about this project, contact the EZSCALE development team.
Status: Base Laravel 12 install in website/ - Ready for Phase 1 Development
Last Updated: February 9, 2026
Total Planning Documents: 7 files, ~4000+ lines of specifications