website/README.md

# 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
- **Gitea**: git@git.ezscale.cloud:EZSCALE/website.git
- **Issues**: https://git.ezscale.cloud/EZSCALE/website/issues
- **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)
- Multi-currency support (per-customer currency, exchange rates)
- Knowledge base with categories and articles

### Not Yet Implemented

- Bandwidth monitoring (ElastiFlow integration) and overage billing
- Blog
- WHMCS data migration (scripts in `scripts/whmcs-migrate/`, artisan commands not yet built)
- CI/CD pipeline
- 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 | 94 |
| Eloquent models | 53 |
| Model factories | 42 |
| Vue pages | 165 |
| Vue components | 54 |
| Test files | 51 |

## 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

```bash
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/              # 53 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/          # 94 migrations
│   ├── factories/           # 24 factories
│   └── seeders/             # Roles, plans, admin, demo data
├── resources/
│   ├── ts/                  # TypeScript source
│   │   ├── Pages/           # 165 Vue pages
│   │   ├── Components/      # 54 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/                   # 51 test files
└── 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**: April 26, 2026
**Total Documentation**: 9 files, ~5900 lines of specifications