Init Commit

2026-02-09 01:05:29 -05:00
commit 052f651ee1
11 changed files with 6038 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,260 @@
+# 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