EZSCALE/website
SHA256
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update README with current project status, optimize CLAUDE.md

Browse Source 
README: reflect completed phases (1-5, 8-9), accurate tech stack
(Vuetify 3 not Tailwind, Passport not Sanctum, standalone tickets
not SupportPal), current codebase counts (59 migrations, 29 models,
85 pages, ~497 tests), and separate implemented vs planned features.

CLAUDE.md: reduce from 281 to 184 lines — trim derivable directory
listings, remove stale counts, cut redundant examples, update all
metrics to current state.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Dev
2026-03-16 11:55:01 -04:00
parent 1d4a9f33f6
commit 2bf8a5b6bf
2 changed files with 268 additions and 375 deletions
Download Patch File Download Diff File Expand all files Collapse all files

392
README.md
View File

@@ -1,268 +1,258 @@
# EZSCALE Billing Platform
Modern Laravel 12 billing and customer management platform replacing WHMCS for EZSCALE Hosting.
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 Strategy**: Feature branches → `develop` → `main`
- **Branch**: `main` (direct commits)
## Documentation Files
| File | Purpose | Lines |
|------|---------|-------|
| **CLAUDE.md** | Project instructions for AI assistance | ~80 |
| **CLAUDE.md** | Project instructions for AI assistance | ~280 |
| **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 | - |
| **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 | - |
## Quick Overview
## Tech Stack
### 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
- **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)
### 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
### 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
| 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) |
### 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
## Current Status: Base Install Complete
### Implemented Features
The **Laravel 12 base installation** exists in the `website/` directory. Planning and documentation is complete. No additional packages or customizations have been added yet.
- 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)
### 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
- [x] Laravel 12 base install created (`website/`)
### Not Yet Implemented
### Next Steps
1. Install core dependencies (Cashier, Fortify, Passport, PayPal, Spatie)
2. Configure environment and database
3. Create database schema and migrations
4. Begin Phase 1: Foundation (auth, database, core setup)
- 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 | 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 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 |
## Infrastructure Integration
### Additional Completed Work (outside phase numbering)
### 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 |
- 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)
### 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 |
## 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
### Payment Gateways
| Gateway | Usage | Integration |
|---------|-------|-------------|
| **Stripe** | Primary (~80%) | Laravel Cashier v16 |
| **PayPal** | Secondary (~20%) | srmklive/laravel-paypal |
| **Crypto** | Optional | Coinbase Commerce |
| **Stripe** | Primary | Laravel Cashier |
| **PayPal** | Secondary | srmklive/paypal |
## Database Overview
## API
### 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
### 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
See **PROJECT_DEVELOPMENT.md** for complete schema with all columns.
### 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
## 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:
```bash
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
```
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/passkeys)
- **Admin**: Email + password + required 2FA (passkeys preferred)
- **Admin Panel**: Behind Cloudflare Zero Trust access control
- **API**: Laravel Sanctum token 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
- HTTPS enforced everywhere
- CSRF protection on all forms
- Rate limiting on auth and API
- CSRF protection on all forms (webhooks exempted)
- Rate limiting on auth and API endpoints
- SQL injection prevention (Eloquent ORM)
- XSS prevention (Blade/Vue escaping + CSP)
### Compliance
- GDPR-compliant automated data deletion
- XSS prevention (Vue escaping)
- 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
- Login history with IP tracking and new-device notifications
- Trusted device management for 2FA
## Analytics & Reporting
### Admin Dashboard
- MRR (Monthly Recurring Revenue)
- ARR (Annual Recurring Revenue)
- Churn rate and customer growth
- MRR and ARR tracking
- Churn rate calculation and trends
- Customer growth chart
- Revenue trends (daily, monthly, yearly)
- Popular plans and conversion rates
- Outstanding invoices
- Popular plans and overdue invoices
### Financial Reports
- Revenue reports (by period, service, plan)
- 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
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.
```
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)
```
**Important**: This machine is for documentation and planning only. The actual project building and code execution happens on a separate development machine.
## WHMCS Migration
## Contact
For questions about this project, contact the EZSCALE development team.
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**: 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
**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