EZSCALE Billing Platform

Modern Laravel 12 billing and customer management platform replacing WHMCS for EZSCALE Hosting. Handles subscription billing, automated service provisioning, customer support, and admin analytics across VPS, Dedicated Server, Web Hosting, and Game Server products.

Repository

• GitHub: git@github.com:EZSCALE/accounting.git
• Branch: main (direct commits)

Documentation Files

File	Purpose	Lines
CLAUDE.md	Project instructions for AI assistance	~280
PROJECT_DEVELOPMENT.md	Complete architecture & development plan	~600
TASKS.md	Detailed task breakdown (13 phases)	~390
FEATURES.md	Feature specifications (35+ features)	~1330
KASM_AND_MULTITENANCY.md	Kasm Workspaces + Multi-Tenancy specs	~930
GETTING_STARTED.md	Development setup guide	~400
ADVANCED_FEATURES.md	Advanced feature specifications (28 features)	~1440
IDEAS.md	Future feature ideas and exploration topics	~530
docs/	Deployment configs, integration specs, scripts	-
scripts/whmcs-migrate/	WHMCS data migration scripts	-
website/	Laravel 12 application	-

Tech Stack

• Framework: Laravel 12 (PHP 8.3)
• Frontend: Vue 3 + Inertia.js v2 + TypeScript + Vuetify 3 + Vite 7
• Design System: Custom EZSCALE theme — navy blue primary (#1d4ed8), Plus Jakarta Sans + JetBrains Mono (Bunny Fonts CDN)
• Charts: ECharts via vue-echarts
• Utilities: @vueuse/core composables, Pinia state management
• Database: MySQL 8.x
• Sessions: Database driver
• Queue: Laravel Horizon
• Payments: Laravel Cashier (Stripe) + srmklive/paypal (PayPal)
• Auth: Laravel Fortify (login, register, 2FA, password reset, email verify) + Passport (OAuth2/SSO for API)
• Roles: spatie/laravel-permission (admin, customer)
• Testing: Pest 4 + PHPUnit 12
• Formatting: Laravel Pint
• PDF: barryvdh/laravel-dompdf (invoices, financial reports)

Domains

Domain (Dev)	Domain (Production)	Purpose
ezscale.dev	ezscale.cloud	Marketing site
account.ezscale.dev	account.ezscale.cloud	Customer dashboard
admin.ezscale.dev	admin.ezscale.cloud	Admin panel (Cloudflare Zero Trust)

Current Status

Implemented Features

• Fully automated provisioning (VPS, Dedicated, Hosting, Game Servers)
• Stripe + PayPal subscription billing with dunning
• Self-service plan upgrades/downgrades with proration
• Coupon system (percentage and fixed discounts)
• Invoice PDF generation and email delivery
• Comprehensive admin panel with MRR/ARR/churn analytics
• Customer management with impersonation, notes, and audit logs
• Service management with soft-delete archive/restore
• Standalone support ticket system with IMAP email integration
• 2FA (TOTP) with trusted device management
• Login history with new-device detection and notifications
• Cancellation surveys and automated win-back campaigns
• Financial reports (Revenue, P&L, Tax, Aging, Refund, Subscription) with PDF/CSV/JSON export
• REST API with Passport auth (customer + admin endpoints, rate-limited)
• 12 marketing pages + 4 legal pages with custom design system
• Notification system (mail + database channels) for payment, subscription, provisioning events
• Command palette (Cmd+K) and dark/light theme toggle
• Demo data seeder (300 customers, 500 subscriptions, 800 invoices)

Not Yet Implemented

• Multi-currency support
• Bandwidth monitoring (ElastiFlow integration) and overage billing
• Blog and knowledge base / FAQ
• WHMCS data migration (scripts in scripts/whmcs-migrate/, artisan commands not yet built)
• CI/CD pipeline (GitHub Actions)
• Staging environment
• Cloudflare Zero Trust configuration for admin panel

Development Phases

Phase	Focus	Status
Phase 1	Foundation & Core Setup	Complete
Phase 2	Billing & Subscriptions	Complete (multi-currency planned)
Frontend	Redesign (Vuexy to custom EZSCALE design system)	Complete
Phase 3	Provisioning Automation	Complete
Phase 4	Customer Dashboard	Mostly Complete (bandwidth graphs depend on Phase 6)
Phase 5	Admin Panel	Complete
Phase 6	Bandwidth Monitoring & Billing	Not Started
Phase 7	SupportPal Integration	Replaced by standalone ticket system
Phase 8	Marketing Frontend	Mostly Complete (blog, KB/FAQ planned)
Phase 9	REST API	Complete
Phase 10	Testing, Migration & Launch	In Progress
Phase 11	Future Enhancements	Backlog
Phase 12	Kasm Workspaces Integration	Planned
Phase 13	Multi-Tenancy (Resellers)	Planned

Additional Completed Work (outside phase numbering)

• Login history and trusted device management
• Churn prevention (cancellation surveys + win-back campaigns)
• Financial reporting suite (6 report types with export)
• Notification system (8 notification types, mail + database)

Codebase at a Glance

Category	Count
Database migrations	59
Eloquent models	29
Model factories	24
Vue pages	85
Vue components	26
Test files	43
Tests	~497
Assertions	~2500

Service Provisioning

Platform	Service Type	API	Status
VirtFusion	VPS	REST API	Implemented
Pterodactyl	Game Servers	REST API	Implemented
SynergyCP	Dedicated Servers	REST API	Implemented
Enhance	Web Hosting	REST API	Implemented

Provisioning is event-driven (triggered by PaymentSucceeded), idempotent (Service::firstOrCreate), and includes automatic retry every 5 minutes via RetryProvisioningCommand.

Support System

Built as a standalone ticket system (not SupportPal):

• Ticket model with replies, departments, priorities, and statuses
• Customer pages: create, view, reply, close tickets
• Admin pages: list (filterable), view, reply, update status
• IMAP email integration: inbound email creates/replies to tickets automatically
• Email threading with [EZSCALE-{id}] references in subject lines
• Scheduled tickets:process-emails command polls IMAP every 2 minutes

Payment Gateways

Gateway	Usage	Integration
Stripe	Primary	Laravel Cashier
PayPal	Secondary	srmklive/paypal

API

Customer API (Passport auth, /api/v1/)

• Services: list, detail, reboot (VPS)
• Invoices: list (filterable), PDF download
• Subscriptions: list, cancel
• Tickets: list, create, detail with replies, reply

Admin API (Passport auth + admin role, /api/v1/admin/)

• Customers: list (searchable/filterable), detail
• Services: list (filterable), detail, suspend, unsuspend
• Analytics: MRR, ARR, churn, growth, revenue by month/type

Rate limiting: 60 requests/min (customer), 120 requests/min (admin). All admin API actions are audit-logged.

Security

Authentication

• Customer: Email + password, optional 2FA (TOTP)
• Admin: Email + password + 2FA
• Admin Panel: Planned Cloudflare Zero Trust access control
• API: Laravel Passport token authentication

Data Protection

• Service credentials encrypted at rest
• CSRF protection on all forms (webhooks exempted)
• Rate limiting on auth and API endpoints
• SQL injection prevention (Eloquent ORM)
• XSS prevention (Vue escaping)
• Full audit trail of admin actions
• Login history with IP tracking and new-device notifications
• Trusted device management for 2FA

Analytics & Reporting

Admin Dashboard

• MRR and ARR tracking
• Churn rate calculation and trends
• Customer growth chart
• Revenue trends (daily, monthly, yearly)
• Popular plans and overdue invoices

Financial Reports

• Revenue reports (by period, service type, plan)
• Profit & Loss statements
• Tax reports (sales tax, VAT)
• Aging reports (overdue invoices)
• Refund reports
• Subscription metrics
• Export: PDF, CSV, JSON

Quick Start

cd website
composer install
npm install
cp .env.example .env
php artisan key:generate

# Configure .env (database, Stripe keys, etc.)
php artisan migrate
php artisan db:seed

# Development
composer run dev    # Starts artisan serve + queue + pail + vite

See GETTING_STARTED.md for the full development setup guide.

Project Layout

website/
├── app/
│   ├── Models/              # 29 Eloquent models
│   ├── Http/Controllers/    # Account/, Admin/, Api/V1/ controllers
│   ├── Http/Resources/      # API Resources
│   ├── Services/Billing/    # Stripe, PayPal, Dunning services
│   ├── Events/              # Payment, Subscription events
│   ├── Listeners/           # Event handlers
│   └── Console/Commands/    # RetryProvisioning, SyncStripePrices, etc.
├── database/
│   ├── migrations/          # 59 migrations
│   ├── factories/           # 24 factories
│   └── seeders/             # Roles, plans, admin, demo data
├── resources/
│   ├── ts/                  # TypeScript source
│   │   ├── Pages/           # 85 Vue pages
│   │   ├── Components/      # 26 Vue components
│   │   ├── Layouts/         # Account, Admin, Auth, Marketing
│   │   ├── stores/          # Pinia stores
│   │   ├── types/           # TypeScript interfaces
│   │   └── plugins/vuetify/ # Theme, defaults, icons
│   └── styles/              # Custom EZSCALE design system (SCSS)
├── routes/                  # web, account, admin, marketing, webhooks, api
├── tests/                   # 43 test files (~497 tests)
└── scripts/whmcs-migrate/   # WHMCS migration scripts (WIP)

WHMCS Migration

Migration from WHMCS is planned for the launch phase. Migration scripts are in scripts/whmcs-migrate/. The migration will cover customers, subscriptions, invoices, payment history, services, and tickets. A 30-day parallel operation period is planned.

---

Status: Active Development — Phases 1-5, 8-9 complete, Phase 10 in progress Last Updated: March 16, 2026 Total Documentation: 9 files, ~5900 lines of specifications