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

Init Commit

Browse Source
This commit is contained in:
Claude EZSCALE
2026-02-09 01:05:29 -05:00
commit 052f651ee1
11 changed files with 6038 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

130
.claude/agents/ezscale-hosting-advisor.md Normal file
View File

@@ -0,0 +1,130 @@
---
name: ezscale-hosting-advisor
description: "Use this agent when the user needs strategic advice, operational improvements, marketing guidance, technical recommendations, or business development support for their VPS/Dedicated Server hosting business (EZSCALE Hosting). This includes pricing strategy, customer acquisition, infrastructure optimization, support workflow improvements, competitive analysis, branding, and growth planning.\\n\\nExamples:\\n\\n<example>\\nContext: The user is asking about how to reduce customer churn.\\nuser: \"I'm losing customers after the first month, what can I do?\"\\nassistant: \"Let me use the EZSCALE Hosting Advisor agent to analyze your churn problem and provide actionable retention strategies.\"\\n<commentary>\\nSince the user is asking about a business problem related to their hosting company, use the Task tool to launch the ezscale-hosting-advisor agent to provide expert advice on customer retention.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: The user wants to improve their pricing structure.\\nuser: \"How should I price my VPS plans to be competitive?\"\\nassistant: \"I'll use the EZSCALE Hosting Advisor agent to develop a competitive pricing strategy for your VPS plans.\"\\n<commentary>\\nSince the user is asking about pricing strategy for their hosting business, use the Task tool to launch the ezscale-hosting-advisor agent to provide market-aware pricing recommendations.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: The user is thinking about expanding their service offerings.\\nuser: \"Should I add managed hosting or cloud services?\"\\nassistant: \"Let me bring in the EZSCALE Hosting Advisor agent to evaluate the opportunity and provide a recommendation on expanding your service portfolio.\"\\n<commentary>\\nSince the user is considering business expansion for their hosting company, use the Task tool to launch the ezscale-hosting-advisor agent to analyze the opportunity.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: The user mentions a technical infrastructure decision.\\nuser: \"I'm deciding between buying hardware or reselling from a larger provider\"\\nassistant: \"I'll use the EZSCALE Hosting Advisor agent to break down the pros, cons, and financial implications of each approach for EZSCALE Hosting.\"\\n<commentary>\\nSince the user is making an infrastructure decision for their hosting business, use the Task tool to launch the ezscale-hosting-advisor agent to provide a thorough analysis.\\n</commentary>\\n</example>"
model: sonnet
memory: project
---
You are a seasoned hosting industry strategist and business consultant with 15+ years of experience building, scaling, and advising VPS and dedicated server hosting companies. You have deep expertise in infrastructure economics, hosting market dynamics, customer lifecycle management, technical operations, and competitive positioning. You've helped hosting companies grow from small operations to significant market players.
You are the dedicated strategic advisor for **EZSCALE Hosting**, a VPS/Dedicated Server hosting provider. Your mission is to help the business owner improve every aspect of their hosting company — from operations and technology to marketing, sales, and customer experience.
## Core Areas of Expertise
### 1. Business Strategy & Positioning
- Market positioning and differentiation in a crowded hosting market
- Identifying and targeting profitable niches (developers, SMBs, gaming, SaaS, agencies, etc.)
- Building a compelling brand identity and value proposition for EZSCALE
- Competitive analysis frameworks specific to the hosting industry
- Revenue diversification strategies (managed services, add-ons, consulting)
### 2. Pricing & Monetization
- VPS and dedicated server pricing strategies that balance competitiveness with profitability
- Plan tier design (resource allocation, feature bundling)
- Upselling and cross-selling strategies (backups, DDoS protection, managed support, SSL, etc.)
- Understanding cost structures: bandwidth, hardware depreciation, licensing, labor
- Billing models: monthly vs. annual, usage-based, credit systems
### 3. Technical Infrastructure & Operations
- Hardware vs. reseller models and hybrid approaches
- Virtualization platform selection (KVM, VMware, Proxmox, etc.)
- Network architecture, peering, and datacenter selection
- Automation and provisioning (WHMCS, Blesta, custom panels)
- Uptime optimization, redundancy, and disaster recovery
- Control panel options (cPanel, Plesk, custom solutions)
- Security hardening and DDoS mitigation strategies
### 4. Customer Acquisition & Marketing
- Digital marketing strategies tailored to hosting (SEO for hosting keywords, PPC, content marketing)
- Community building and developer relations
- Affiliate and referral programs
- Review site optimization (Trustpilot, G2, HostAdvice, etc.)
- Social media and content strategies that work for B2B hosting
- Partnership and channel sales opportunities
### 5. Customer Retention & Support
- Support ticket workflow optimization
- SLA design and enforcement
- Proactive monitoring and customer communication
- Churn reduction strategies specific to hosting
- Customer success programs and onboarding flows
- Building loyalty through transparency and reliability
### 6. Financial & Operational Management
- Unit economics for hosting (CAC, LTV, margin analysis)
- Scaling operations efficiently (when to hire, what to automate)
- Legal considerations (ToS, AUP, GDPR, data privacy)
- Vendor negotiations and procurement strategy
## How You Operate
1. **Always contextualize for EZSCALE**: Frame all advice specifically for EZSCALE Hosting's situation. Ask clarifying questions about their current state — number of customers, revenue range, infrastructure setup, team size, target market — before giving advice when this context is missing.
2. **Be actionable**: Don't just say "improve your marketing." Give specific steps, tools, timelines, and expected outcomes. Prioritize recommendations by impact and effort.
3. **Think like a hosting operator**: You understand the real-world challenges — tight margins, price-sensitive customers, 24/7 uptime expectations, abuse handling, and the constant pressure from hyperscalers (AWS, GCP, Azure). Your advice accounts for these realities.
4. **Provide frameworks, not just answers**: When analyzing a problem, walk through your reasoning. Use frameworks like SWOT, Porter's Five Forces, or customer journey mapping when appropriate.
5. **Be honest about trade-offs**: If a strategy has downsides, say so. If the user is making a mistake, respectfully point it out with data-backed reasoning.
6. **Benchmark against industry standards**: Reference what successful hosting companies (Hetzner, OVH, DigitalOcean, Vultr, Linode, Contabo, etc.) do well and what EZSCALE can learn from them at their scale.
7. **Prioritize profitability**: Growth is important, but not at the expense of sustainability. Always consider the financial impact of recommendations.
## Output Format
When providing recommendations:
- Start with a brief assessment of the current situation or question
- Provide prioritized, numbered action items
- Include estimated effort level (Low/Medium/High) and potential impact (Low/Medium/High) for each recommendation
- Offer quick wins alongside long-term strategic plays
- End with suggested next steps or questions to explore further
When analyzing a specific area:
- Present findings in a structured format with clear headers
- Use tables or comparison matrices when comparing options
- Include specific metrics to track success
## Update Your Agent Memory
As you learn about EZSCALE Hosting's business, update your agent memory with key details. This builds institutional knowledge across conversations so you can provide increasingly tailored advice.
Examples of what to record:
- EZSCALE's current infrastructure setup (datacenter locations, virtualization platform, control panels)
- Customer base size, target market, and demographics
- Current pricing structure and plan tiers
- Revenue figures, margins, and financial goals
- Team size and roles
- Known pain points, challenges, and past decisions
- Competitive positioning and key differentiators
- Marketing channels currently in use and their performance
- Technology stack (billing system, automation tools, monitoring)
- Strategic goals and timeline
## Important Reminders
- The hosting industry is highly competitive with thin margins — every recommendation must be practical and cost-conscious
- EZSCALE is the user's business and brand; treat it with the seriousness and care it deserves
- When you don't know something specific about EZSCALE's situation, ask — don't assume
- Stay current on hosting industry trends: edge computing, cloud-native, containerization, green hosting, AI workloads
- Remember that the user may be a technical founder wearing many hats — keep advice accessible and prioritized
# Persistent Agent Memory
You have a persistent Persistent Agent Memory directory at `/root/projects/ezscale_site/.claude/agent-memory/ezscale-hosting-advisor/`. Its contents persist across conversations.
As you work, consult your memory files to build on previous experience. When you encounter a mistake that seems like it could be common, check your Persistent Agent Memory for relevant notes — and if nothing is written yet, record what you learned.
Guidelines:
- `MEMORY.md` is always loaded into your system prompt — lines after 200 will be truncated, so keep it concise
- Create separate topic files (e.g., `debugging.md`, `patterns.md`) for detailed notes and link to them from MEMORY.md
- Record insights about problem constraints, strategies that worked or failed, and lessons learned
- Update or remove memories that turn out to be wrong or outdated
- Organize memory semantically by topic, not chronologically
- Use the Write and Edit tools to update your memory files
- Since this memory is project-scope and shared with your team via version control, tailor your memories to this project
## MEMORY.md
Your MEMORY.md is currently empty. As you complete tasks, write down key learnings, patterns, and insights so you can be more effective in future conversations. Anything saved in MEMORY.md will be included in your system prompt next time.

8
.claude/settings.local.json Normal file
View File

@@ -0,0 +1,8 @@
{
"permissions": {
"allow": [
"WebSearch",
"Bash(ls:*)"
]
}
}

1444
ADVANCED_FEATURES.md Normal file
View File

File diff suppressed because it is too large Load Diff

73
CLAUDE.md Normal file
View File

@@ -0,0 +1,73 @@
# CLAUDE.md - EZSCALE Site Project Instructions
## Important Context
- This repository is used for **documentation and planning only** on this machine
- Actual project building and code execution happens on a separate development machine
- Do NOT attempt to run composer, php, node, or other build commands here
- Focus on documentation, architecture, and planning tasks
## Project Overview
EZSCALE Site is a Laravel 12 application replacing WHMCS for VPS/Dedicated Server hosting management. It handles billing, subscriptions, provisioning, customer management, and SSO.
## Tech Stack
- **Framework:** Laravel 12 (PHP 8.2+)
- **Frontend:** Vue 3 + Inertia.js + Tailwind CSS
- **UI Theme:** Vuexy VueJS + Laravel Admin Dashboard Template (source files to be added)
- **Payments:** Laravel Cashier Stripe (primary) + srmklive/laravel-paypal (secondary)
- **Database:** MySQL 8.x
- **Queue:** Redis
- **Auth:** Laravel Fortify + Passport (OAuth2/SSO)
- **Roles:** spatie/laravel-permission
## Project Structure
```
app/
├── Models/ # Eloquent models
├── Http/
│ ├── Controllers/ # Route controllers
│ ├── Middleware/ # Custom middleware
│ └── Requests/ # Form request validation
├── Services/ # Business logic (provisioning, billing, etc.)
├── Policies/ # Authorization policies
└── Events/ # Domain events
```
## Development Commands
```bash
php artisan serve # Run dev server
php artisan test # Run test suite
php artisan migrate # Run migrations
php artisan queue:work # Process queue jobs
npm run dev # Vite dev server
npm run build # Production build
```
## Code Conventions
- Follow PSR-12 coding standards
- Use strict typing: `declare(strict_types=1);` in all PHP files
- Use Form Request classes for validation
- Use Service classes for business logic (not in controllers)
- Use Policies for authorization
- Use Events/Listeners for side effects (email, provisioning, etc.)
- Write Feature and Unit tests for all new functionality
- Use database transactions for multi-step operations
## Security Requirements
- All API endpoints require authentication
- Admin routes protected by role-based middleware
- CSRF protection on all forms
- Rate limiting on auth and API endpoints
- Input sanitization on all user inputs
- Encrypted storage for sensitive data (API keys, credentials)
- Audit logging for admin actions and billing events
## Key Domains
1. **Billing** - Subscriptions, invoices, payments via Cashier
2. **Provisioning** - Server creation, suspension, termination
3. **Customer Management** - Profiles, support tickets, notifications
4. **Admin Panel** - Dashboard, user management, server management
5. **SSO** - Single sign-on across EZSCALE services
## Reference Files
- `TASKS.md` - Current task list and progress
- `PROJECT_DEVELOPMENT.md` - Architecture decisions and development plan

1332
FEATURES.md Normal file
View File

File diff suppressed because it is too large Load Diff

393
GETTING_STARTED.md Normal file
View File

@@ -0,0 +1,393 @@
# Getting Started - EZSCALE Billing Platform Development
This guide will help you start building the EZSCALE Billing Platform on your development machine.
## Prerequisites
### Required Software
- **PHP** 8.2 or higher
- **Composer** 2.x
- **Node.js** 18.x or higher
- **npm** 9.x or higher
- **MySQL** 8.0 or higher
- **Redis** 6.x or higher
- **Git**
### Optional but Recommended
- **Laravel Herd** (all-in-one Laravel development environment)
- **TablePlus** or **MySQL Workbench** (database GUI)
- **Redis Desktop Manager** (Redis GUI)
- **Postman** or **Insomnia** (API testing)
## Step 1: Clone Repository
```bash
# Clone the repository
git clone git@github.com:EZSCALE/accounting.git ezscale_billing
cd ezscale_billing
# Create develop branch
git checkout -b develop
```
## Step 2: Initialize Laravel 12 Project
Since this is currently just documentation, you'll initialize a fresh Laravel 12 project:
```bash
# Install Laravel 12 with Vue + Inertia starter kit
composer create-project laravel/laravel .
# During installation, select:
# - Starter kit: Vue + Inertia
# - Testing framework: Pest
# - Database: MySQL
```
## Step 3: Configure Environment
```bash
# Copy the planning files (already in repo)
# .env file should already exist, update it:
APP_NAME="EZSCALE Billing"
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=ezscale_billing
DB_USERNAME=root
DB_PASSWORD=your_password
REDIS_CLIENT=phpredis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379
# Stripe keys (get from Stripe dashboard)
STRIPE_KEY=pk_test_...
STRIPE_SECRET=sk_test_...
# PayPal credentials (get from PayPal developer dashboard)
PAYPAL_MODE=sandbox
PAYPAL_SANDBOX_CLIENT_ID=...
PAYPAL_SANDBOX_CLIENT_SECRET=...
# Email (choose Mailgun or SendGrid)
MAIL_MAILER=smtp
MAIL_HOST=smtp.mailgun.org
MAIL_PORT=587
MAIL_USERNAME=...
MAIL_PASSWORD=...
MAIL_FROM_ADDRESS=noreply@ezscale.cloud
MAIL_FROM_NAME="EZSCALE Hosting"
# Discord webhook for admin alerts
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
```
## Step 4: Create Database
```bash
# Connect to MySQL
mysql -u root -p
# Create database
CREATE DATABASE ezscale_billing CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
EXIT;
```
## Step 5: Install Dependencies
```bash
# Install PHP dependencies
composer require laravel/cashier
composer require laravel/fortify
composer require laravel/passport
composer require srmklive/laravel-paypal
composer require spatie/laravel-permission
composer require --dev laravel/telescope
# Install Node dependencies
npm install
```
## Step 6: Add Vuexy Theme
```bash
# Extract Vuexy theme source files to:
# resources/js/vuexy/
# resources/css/vuexy/
# Update vite.config.js to include Vuexy assets
# Update app.js to import Vuexy components
# Detailed integration instructions in Vuexy documentation
```
## Step 7: Run Migrations
```bash
# Generate app key
php artisan key:generate
# Run Laravel's default migrations
php artisan migrate
# Publish Cashier migrations
php artisan vendor:publish --tag="cashier-migrations"
# Publish Passport migrations
php artisan passport:install
# Publish Spatie migrations
php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"
# Now create your custom migrations (see PROJECT_DEVELOPMENT.md for schema)
# php artisan make:migration create_user_profiles_table
# php artisan make:migration create_plans_table
# ... etc
# Run all migrations
php artisan migrate
```
## Step 8: Seed Initial Data
```bash
# Create seeders
php artisan make:seeder RoleSeeder
php artisan make:seeder PlanSeeder
php artisan make:seeder DatacenterSeeder
# Run seeders
php artisan db:seed
```
## Step 9: Configure Authentication
```bash
# Publish Fortify views
php artisan vendor:publish --tag=fortify-views
# Install Fortify
php artisan fortify:install
# Configure Fortify features in config/fortify.php
# Enable: registration, reset passwords, email verification, two factor
# Set up Passport for OAuth2 (SSO later)
php artisan passport:install
```
## Step 10: Start Development Servers
```bash
# Terminal 1: Start Laravel server
php artisan serve
# Terminal 2: Start Vite dev server
npm run dev
# Terminal 3: Start queue worker
php artisan queue:work
# Optional Terminal 4: Start Horizon (queue monitoring)
php artisan horizon
```
## Step 11: Configure Local Domains (Optional)
If using Laravel Herd or Valet, you can set up local domains:
```bash
# With Herd/Valet
ezscale.test -> Marketing site
account.ezscale.test -> Customer dashboard
admin.ezscale.test -> Admin panel
```
Update `.env`:
```
APP_URL=http://ezscale.test
```
## Step 12: Set Up Testing
```bash
# Create test database
CREATE DATABASE ezscale_billing_test;
# Update phpunit.xml or .env.testing
DB_DATABASE=ezscale_billing_test
# Run tests
php artisan test
```
## Development Workflow
### Daily Development
```bash
# Pull latest changes
git pull origin develop
# Install any new dependencies
composer install
npm install
# Run migrations
php artisan migrate
# Start dev servers
php artisan serve
npm run dev
php artisan queue:work
```
### Creating Features
```bash
# Create feature branch from develop
git checkout develop
git pull
git checkout -b feature/billing-system
# Make changes, commit often
git add .
git commit -m "Add Stripe billing service"
# Push to remote
git push origin feature/billing-system
# Create PR on GitHub: feature/billing-system -> develop
```
### Running Tests
```bash
# Run all tests
php artisan test
# Run specific test
php artisan test --filter BillingServiceTest
# Run with coverage
php artisan test --coverage
```
## Phase 1 Checklist
Use this checklist to track Phase 1 Foundation progress:
- [ ] Laravel 12 project initialized
- [ ] Vuexy theme integrated
- [ ] Environment configured (.env)
- [ ] Database created and connected
- [ ] All dependencies installed (Cashier, Fortify, Passport, PayPal, Spatie)
- [ ] Custom migrations created (see PROJECT_DEVELOPMENT.md for full schema)
- [ ] user_profiles
- [ ] plans
- [ ] datacenters
- [ ] payment_transactions
- [ ] services
- [ ] provisioning_logs
- [ ] bandwidth_usage
- [ ] audit_logs
- [ ] support_tickets (mirror)
- [ ] announcements
- [ ] Migrations run successfully
- [ ] Seeders created and run
- [ ] Fortify authentication configured
- [ ] Passport OAuth2 set up
- [ ] Spatie roles configured (admin, customer)
- [ ] Redis working
- [ ] Queue working
- [ ] Email sending working (test with Mailtrap initially)
- [ ] Git repository initialized
- [ ] CI/CD pipeline set up (GitHub Actions)
- [ ] Staging environment created
## Common Issues & Solutions
### Issue: Composer dependencies conflict
**Solution**: Check PHP version (must be 8.2+), update composer.json constraints
### Issue: npm install fails
**Solution**: Delete node_modules and package-lock.json, run `npm install` again
### Issue: Database connection refused
**Solution**: Check MySQL is running, verify credentials in .env
### Issue: Redis connection failed
**Solution**: Start Redis server: `redis-server` or check if running with `redis-cli ping`
### Issue: Vite not compiling
**Solution**: Clear Vite cache: `npm run build`, restart `npm run dev`
### Issue: Queue jobs not processing
**Solution**: Ensure `php artisan queue:work` is running, check Redis connection
## API Credentials You'll Need
Before full development, obtain these API credentials:
### Payment Gateways
- [ ] Stripe test keys (pk_test_, sk_test_)
- [ ] Stripe production keys (pk_live_, sk_live_)
- [ ] PayPal sandbox credentials
- [ ] PayPal production credentials
### Provisioning APIs
- [ ] VirtFusion API key
- [ ] Pterodactyl API token
- [ ] SynergyCP API credentials
- [ ] Enhance API key
### External Services
- [ ] SupportPal API credentials
- [ ] ElastiFlow API access
- [ ] Mailgun or SendGrid API key
- [ ] Discord webhook URL
- [ ] Twilio credentials (for SMS alerts - optional)
- [ ] Cloudflare API token (for DNS integration)
- [ ] Coinbase Commerce API (for crypto payments - optional)
### Development Tools
- [ ] GitHub personal access token (for Actions)
- [ ] Sentry DSN (for error tracking - optional)
## Documentation Reference
As you build, refer to these files:
| File | When to Reference |
|------|-------------------|
| **PROJECT_DEVELOPMENT.md** | Architecture decisions, database schema, API integrations |
| **TASKS.md** | Task checklist, what to build in each phase |
| **FEATURES.md** | Detailed feature specifications, implementation notes |
| **CLAUDE.md** | Code conventions, security requirements |
## Next Steps After Phase 1
Once Phase 1 is complete:
1. Review Phase 1 deliverables
2. Demo authentication flow
3. Verify all integrations are working (test API connections)
4. Begin Phase 2: Billing & Subscriptions
## Getting Help
- **Laravel Documentation**: https://laravel.com/docs/12.x
- **Vuexy Documentation**: Check included docs in theme package
- **Cashier Documentation**: https://laravel.com/docs/12.x/billing
- **Project Planning Docs**: See CLAUDE.md, PROJECT_DEVELOPMENT.md, FEATURES.md
## Development Team
Add team member contact information here as project progresses.
---
**Ready to build?** Start with Phase 1 tasks from TASKS.md!

531
IDEAS.md Normal file
View File

@@ -0,0 +1,531 @@
# IDEAS.md - Future Feature Ideas & Exploration Topics
This document contains ideas for future exploration and features that haven't been fully planned yet. Use this as a starting point for future planning sessions.
---
## 1. Integration with Specific Tools
### Monitoring & Observability
- **Grafana Integration**: Embed Grafana dashboards in customer portal
- **Prometheus Metrics**: Expose service metrics for customer scraping
- **Datadog/New Relic**: Pre-configured APM for customer applications
- **Sentry Integration**: Error tracking for customer apps with EZSCALE-managed Sentry
- **PagerDuty/OpsGenie**: Incident management integration for enterprise customers
### Analytics & Business Intelligence
- **Google Analytics 4**: Deep integration for marketing site and customer behavior
- **Mixpanel/Amplitude**: Product analytics for customer journey tracking
- **Segment**: Customer data platform for unified analytics
- **Metabase/Redash**: Embedded business intelligence dashboards
### Development Tools
- **GitHub Actions Runners**: Offer hosted GitHub Actions runners as a service
- **GitLab CI/CD**: Managed GitLab runners for customer pipelines
- **Docker Registry**: Private Docker registry hosting per customer
- **Kubernetes Clusters**: Managed K8s clusters (EKS/GKE-style offering)
### Communication Tools
- **Slack Integration**: Service alerts to customer Slack channels
- **Microsoft Teams**: Notifications and bot commands
- **Webhook Relays**: Reliable webhook delivery service
- **SMS Alerts**: Twilio integration for critical service alerts
---
## 2. Advanced Security Features
### Enhanced Authentication
- **Hardware Security Keys**: YubiKey, Titan Key support (beyond passkeys)
- **Biometric Authentication**: TouchID/FaceID for mobile web
- **Certificate-Based Auth**: Client certificates for API access
- **SAML/OIDC Provider**: Act as identity provider for customer apps
### Security Scanning
- **Vulnerability Scanning**: Automated CVE scanning for customer VPS
- **Container Security**: Scan Docker images for vulnerabilities
- **SSL/TLS Monitoring**: Cert expiry tracking and auto-renewal alerts
- **Security Scorecard**: Customer-facing security posture dashboard
### Compliance & Auditing
- **HIPAA Compliance**: BAA agreements, encrypted backups, audit logging
- **PCI DSS**: For customers processing payments
- **FedRAMP**: Government cloud compliance (long-term)
- **Automated Compliance Reports**: Generate SOC 2, ISO 27001 evidence
### Advanced Threat Protection
- **WAF (Web Application Firewall)**: ModSecurity integration or Cloudflare
- **SIEM Integration**: Security Information and Event Management
- **Intrusion Detection**: IDS/IPS for network monitoring
- **Honeypot Services**: Decoy services to detect attackers
---
## 3. International & Localization Features
### Multi-Language Support
- **UI Translation**: Support for 10+ languages (ES, FR, DE, PT, ZH, JA, KO)
- **RTL Languages**: Right-to-left support (Arabic, Hebrew)
- **Currency Localization**: Display prices in local currency
- **Date/Time Formats**: Region-appropriate formatting
### Regional Compliance
- **GDPR Tools**: Cookie consent, data portability, deletion workflows
- **China Compliance**: ICP licensing support for Chinese customers
- **Brazil LGPD**: Brazilian data protection compliance
- **Australia Privacy Act**: Regional compliance features
### Geographic Expansion
- **Multi-Region Support**: Add Asia-Pacific, EU, South America datacenters
- **Region Selection UI**: Map-based datacenter selection
- **Latency Testing**: Pre-purchase latency tests from customer location
- **Local Payment Methods**: Alipay, WeChat Pay, PIX (Brazil), UPI (India)
### Tax Complexity
- **VAT MOSS**: EU VAT Mini One Stop Shop
- **GST Support**: Goods and Services Tax (India, Australia, Canada)
- **Local Tax Integrations**: Country-specific tax API integrations
- **Tax Exemption Certificates**: Upload and validate tax exemption docs
---
## 4. More Automation & AI Capabilities
### Predictive Analytics
- **Churn Prediction**: ML model to predict customer churn before it happens
- **Usage Forecasting**: Predict future resource needs weeks in advance
- **Anomaly Detection**: Auto-detect unusual patterns (security or performance)
- **Revenue Forecasting**: Predict MRR/ARR based on trends
### Intelligent Automation
- **Auto-Scaling**: Automatically upgrade services when hitting resource limits
- **Smart Scheduling**: AI-optimized task scheduling (backups during low usage)
- **Capacity Planning**: AI suggests when to add hypervisors based on growth
- **Resource Right-Sizing**: Continuously optimize resource allocation
### Conversational AI
- **Voice Assistant**: "Alexa, what's my current server status?"
- **Natural Language Commands**: "Create a VPS in New York with 4GB RAM"
- **Smart Search**: Semantic search across docs, services, tickets
- **Personalized Recommendations**: AI suggests services based on usage patterns
### Automated Support
- **Ticket Categorization**: Auto-tag and route tickets to right team
- **Response Suggestions**: Suggest replies to common support questions
- **Knowledge Base AI**: Auto-generate KB articles from resolved tickets
- **Sentiment Analysis**: Detect frustrated customers, prioritize their tickets
---
## 5. Advanced Networking Features
### Software-Defined Networking
- **Virtual Private Cloud (VPC)**: Isolated networks per customer
- **VPN-as-a-Service**: Managed WireGuard/OpenVPN servers
- **Private Interconnects**: High-speed links between datacenters
- **Network ACLs**: Firewall rules at network level
### Load Balancing & Traffic Management
- **Managed Load Balancers**: HAProxy, NGINX as a service
- **Global Load Balancing**: GeoDNS-based traffic routing
- **DDoS Mitigation**: Wanguard integration (mentioned earlier)
- **CDN Integration**: Built-in CDN for static content
### DNS Management
- **Managed DNS Service**: Authoritative DNS hosting
- **DNSSEC**: Secure DNS with signing
- **Dynamic DNS**: DynDNS-style service for changing IPs
- **DNS Analytics**: Query analytics and threat detection
### IPv6 Advanced
- **IPv6-Only Plans**: Cheaper plans with IPv6-only (NAT64 for legacy)
- **Prefix Delegation**: Customer can delegate subnets
- **IPv6 Rapid Deployment**: Auto-configure IPv6 for new services
---
## 6. Platform-as-a-Service (PaaS) Features
### Application Hosting
- **One-Click Apps**: WordPress, Drupal, Magento, Ghost, etc.
- **Container Platform**: Managed Docker/Kubernetes for apps
- **Serverless Functions**: AWS Lambda-style FaaS
- **Static Site Hosting**: Netlify/Vercel competitor
### Database-as-a-Service
- **Managed MySQL**: HA MySQL clusters
- **Managed PostgreSQL**: With point-in-time recovery
- **Managed Redis**: Redis cluster management
- **Managed MongoDB**: NoSQL database service
### Development Platforms
- **CI/CD Pipelines**: Hosted build and deployment
- **Preview Environments**: Auto-deploy PR previews
- **Code Repositories**: Hosted Git (GitLab-style)
- **Development Workspaces**: More Kasm integration (IDE-as-a-Service)
---
## 7. Enterprise Features
### Multi-Organization Support
- **Organization Hierarchy**: Parent/child org structures
- **Consolidated Billing**: Bill parent org for all child orgs
- **Cross-Org Resource Sharing**: Share resources between orgs
- **Org-Level Policies**: Enforce security policies across org
### Advanced Billing
- **Usage-Based Pricing**: Per-API-call, per-GB-transferred pricing
- **Committed Use Discounts**: Discount for 1-3 year commitments
- **Volume Licensing**: Tiered pricing based on total spend
- **Purchase Orders**: PO support for enterprise customers
### Service Level Agreements (SLA)
- **Uptime SLAs**: 99.9%, 99.95%, 99.99% tiers with credits
- **Support SLAs**: Response time guarantees
- **SLA Credits**: Automatic credit issuance for breaches
- **Custom SLAs**: Negotiated agreements for enterprise
### Professional Services
- **Migration Services**: Migrate from competitor (DigitalOcean, AWS, etc.)
- **Architecture Consulting**: Design customer infrastructure
- **Training Programs**: Certification courses for EZSCALE platform
- **Managed Services**: White-glove management of customer infrastructure
---
## 8. Marketplace & Ecosystem
### Third-Party Add-Ons
- **Plugin Marketplace**: Third-party tools and integrations
- **Partner Services**: Vetted partners (backup, monitoring, security)
- **Revenue Sharing**: Partners sell through EZSCALE, revenue split
- **API for Partners**: Partner API for deep integrations
### Developer Ecosystem
- **SDK Libraries**: Official SDKs (Python, PHP, Node.js, Go, Ruby)
- **CLI Tool**: Command-line tool for EZSCALE management
- **VS Code Extension**: Manage services from VS Code
- **Postman Collection**: Pre-built API collection
### Community Contributions
- **Open Source Templates**: Community-contributed server configs
- **Automation Scripts**: Share Ansible/Terraform configs
- **Community Leaderboard**: Top contributors get rewards
- **Bounty Program**: Pay for feature requests, bug reports
---
## 9. Advanced Customer Experience
### Self-Service Portal Enhancements
- **Custom Dashboards**: Drag-and-drop dashboard builder
- **Saved Filters**: Save common service filters
- **Bulk Actions**: Select multiple services, perform actions
- **Quick Actions**: Keyboard shortcuts for power users
### Mobile Experience
- **Progressive Web App**: Installable, offline-capable
- **Mobile Notifications**: Push notifications for mobile devices
- **Touch-Optimized UI**: Better mobile gestures
- **Mobile-First Features**: Quick actions, simplified views
### Accessibility
- **WCAG 2.1 AA Compliance**: Full accessibility support
- **Screen Reader Optimization**: Semantic HTML, ARIA labels
- **Keyboard Navigation**: Full keyboard accessibility
- **High Contrast Mode**: For visually impaired users
### Personalization
- **Dashboard Themes**: Light, dark, custom themes
- **Widget Customization**: Show/hide dashboard widgets
- **Default Views**: Remember user preferences
- **Recommended Services**: Based on usage patterns
---
## 10. Environmental & Sustainability
### Green Hosting
- **Carbon Neutral Datacenters**: 100% renewable energy
- **Carbon Offset Program**: Offset customer infrastructure
- **Energy Efficiency Metrics**: Show power usage effectiveness (PUE)
- **Green Badges**: Highlight eco-friendly service options
### Efficiency Reporting
- **Power Usage Dashboard**: Show energy consumption
- **Efficiency Score**: Grade services on energy efficiency
- **Optimization Suggestions**: Reduce power consumption tips
- **Sustainability Report**: Annual sustainability report for customers
---
## 11. Financial & Payment Enhancements
### Alternative Payment Methods
- **Buy Now, Pay Later**: Affirm, Klarna integration
- **ACH/Bank Transfer**: Direct bank payments
- **Wire Transfers**: For large enterprise payments
- **Cryptocurrency Wallets**: Native wallet integration (not just Coinbase)
### Financial Management
- **Expense Categorization**: Tag expenses for accounting
- **Multi-Entity Billing**: Bill different legal entities separately
- **Tax Documents**: Auto-generate 1099s, VAT invoices
- **Financial Forecasting**: Predict future spend based on usage
### Revenue Optimization
- **Dynamic Pricing**: Adjust prices based on demand
- **Promotional Pricing**: Time-limited offers, flash sales
- **Bundle Discounts**: Discount for service bundles
- **Loyalty Pricing**: Better pricing for long-term customers
---
## 12. Advanced Monitoring & Observability
### Application Performance Monitoring
- **Built-in APM**: Monitor app performance without external tools
- **Distributed Tracing**: Trace requests across microservices
- **Log Aggregation**: Centralized logging service
- **Metrics Dashboard**: Custom metrics from customer apps
### Infrastructure Monitoring
- **Node Exporter**: Prometheus node metrics
- **Custom Metrics API**: Push custom metrics to platform
- **Alerting Rules**: Custom alert rules based on metrics
- **Anomaly Detection**: ML-based anomaly detection
### Synthetic Monitoring
- **Uptime Checks**: Monitor from multiple global locations
- **API Monitoring**: Test API endpoints periodically
- **Performance Budgets**: Alert when performance degrades
- **Transaction Monitoring**: Monitor critical user flows
---
## 13. Disaster Recovery & Business Continuity
### Backup Enhancements
- **Geo-Redundant Backups**: Store backups in multiple regions
- **Backup Encryption**: Customer-managed encryption keys
- **Backup Testing**: Automated restore testing
- **Backup Retention Policies**: Customizable retention rules
### Disaster Recovery
- **DR-as-a-Service**: Managed disaster recovery
- **Failover Automation**: Auto-failover to DR site
- **RPO/RTO Targets**: Guarantee recovery objectives
- **DR Testing**: Scheduled DR drills
### High Availability
- **Active-Active Deployments**: Multi-region active setups
- **Database Replication**: Real-time multi-region replication
- **Zero-Downtime Migrations**: Live migration between hypervisors
- **Chaos Engineering**: Test resilience with controlled failures
---
## 14. Developer Experience (DevEx)
### API Enhancements
- **GraphQL API**: Alternative to REST API
- **WebSocket API**: Real-time API for streaming updates
- **gRPC Support**: High-performance RPC protocol
- **API Versioning**: Maintain old API versions for compatibility
### Testing & Staging
- **Sandbox Environments**: Test API calls without real charges
- **Staging Infrastructure**: Clone prod to staging
- **Feature Flags**: Test features before full release
- **A/B Testing Framework**: Built-in A/B testing for customer apps
### Documentation
- **Interactive API Docs**: Try API calls directly in docs
- **Code Generators**: Generate API client code
- **Tutorials & Guides**: Step-by-step integration guides
- **Video Tutorials**: Screencasts for common tasks
---
## 15. Data & Analytics
### Customer Analytics
- **User Behavior Tracking**: How customers use the platform
- **Feature Adoption**: Which features are used most
- **Drop-off Analysis**: Where customers abandon flows
- **Session Recording**: Watch customer sessions (privacy-conscious)
### Business Intelligence
- **Executive Dashboard**: High-level metrics for leadership
- **Predictive Reports**: Forecast future performance
- **Benchmarking**: Compare against industry averages
- **Data Warehouse**: Export all data to customer's warehouse
### Data Export & Portability
- **Bulk Export API**: Export all customer data
- **Data Pipeline**: Stream data to customer systems
- **Webhook Replay**: Replay missed webhooks
- **Audit Log Export**: Compliance-friendly log exports
---
## 16. Unique/Innovative Ideas
### Blockchain Integration
- **NFT-Based Licensing**: Server licenses as NFTs
- **Smart Contracts**: Billing via smart contracts
- **Decentralized Storage**: IPFS integration for backups
- **Crypto Mining Protection**: Detect and prevent mining abuse
### AI-Powered Infrastructure
- **Auto-Remediation**: AI fixes common issues automatically
- **Predictive Maintenance**: Predict hardware failures before they happen
- **Intelligent Routing**: AI-optimized traffic routing
- **Resource Allocation**: AI decides optimal resource placement
### Experimental Services
- **Edge Computing**: Deploy to edge locations near users
- **GPU Instances**: For ML/AI workloads
- **FPGA Instances**: For specialized compute
- **Quantum Computing**: Access to quantum computers (future)
### Social Features
- **Server Showcases**: Customers show off their setups
- **Competitions**: Hackathons, best setup contests
- **User Groups**: Regional or topic-based user groups
- **Events & Meetups**: EZSCALE-hosted community events
---
## 17. Operational Efficiency
### Automation
- **Runbook Automation**: Auto-execute common operational tasks
- **Self-Healing**: Auto-fix detected issues
- **Automated Scaling**: Scale infrastructure based on demand
- **Smart Scheduling**: AI-optimized maintenance windows
### Internal Tools
- **Admin Mobile App**: Manage platform from mobile
- **Incident Management**: Structured incident response workflow
- **Change Management**: Track and approve infrastructure changes
- **Knowledge Management**: Internal wiki for team
### Customer Success
- **Health Scores**: Track customer health (NPS, usage, support)
- **Proactive Outreach**: Reach out before customers churn
- **Success Plans**: Onboarding and growth plans
- **Executive Business Reviews**: Quarterly reviews with enterprise customers
---
## 18. Reseller & Partner Program Enhancements
### Reseller Tools
- **White-Label Mobile App**: Branded mobile apps for resellers
- **Custom API Domain**: api.reseller.com instead of api.ezscale.cloud
- **Reseller Analytics**: Track reseller performance
- **Marketing Materials**: Co-branded marketing assets
### Partner Integrations
- **Technology Partners**: Deep integrations with complementary services
- **Channel Partners**: Agencies selling EZSCALE
- **OEM Partnerships**: Embed EZSCALE in other products
- **Affiliate Network**: Broader affiliate program
---
## 19. Emerging Technologies
### Web3 & Decentralization
- **Decentralized Identity**: DID for customer authentication
- **Token-Based Economy**: Loyalty tokens, governance tokens
- **DAO Governance**: Customer voting on feature roadmap
- **Decentralized Support**: Community-powered support with token rewards
### AR/VR
- **VR Data Center Tours**: Virtual tour of datacenters
- **AR Troubleshooting**: AR overlays for server maintenance
- **3D Infrastructure Visualization**: Visualize infrastructure in 3D
### IoT Integration
- **IoT Device Management**: Manage customer IoT devices
- **Edge Processing**: Process IoT data at edge
- **Device Provisioning**: Auto-provision devices
- **IoT Analytics**: Analyze device data
---
## 20. Content & Education
### Learning Platform
- **EZSCALE Academy**: Courses on hosting, DevOps, cloud
- **Certification Program**: Certified EZSCALE Administrator
- **Webinars**: Regular educational webinars
- **Workshops**: Hands-on training sessions
### Content Library
- **Case Studies**: Success stories from customers
- **White Papers**: Technical deep-dives
- **Benchmarks**: Performance comparisons
- **Industry Reports**: State of hosting industry
### Community Resources
- **Blog Platform**: Customer blogging on EZSCALE subdomain
- **Podcast**: EZSCALE-hosted tech podcast
- **YouTube Channel**: Tutorials, interviews, updates
- **Newsletter**: Weekly/monthly newsletter
---
## Implementation Priority Framework
When deciding which ideas to implement, consider:
### Priority Matrix
**High Impact + Easy to Implement:**
- Quick wins, do these first
- Examples: Basic monitoring integrations, simple automation
**High Impact + Hard to Implement:**
- Strategic investments, plan carefully
- Examples: Full PaaS, multi-region expansion
**Low Impact + Easy to Implement:**
- Nice-to-haves, do when time permits
- Examples: Dashboard themes, minor UI improvements
**Low Impact + Hard to Implement:**
- Probably skip these
- Examples: Blockchain features (unless business model changes)
### Decision Criteria
1. **Customer Demand**: Are customers asking for it?
2. **Competitive Advantage**: Does it differentiate from competitors?
3. **Revenue Impact**: Will it increase revenue or reduce churn?
4. **Technical Feasibility**: Can we build it with current team/resources?
5. **Strategic Fit**: Aligns with company vision and roadmap?
---
## Next Steps
When ready to explore any of these ideas:
1. **Review this document** - Pick 2-3 ideas that seem most valuable
2. **Deep dive session** - Spend time planning the selected ideas in detail
3. **Prototype** - Build quick proof-of-concept for validation
4. **Customer research** - Survey customers on the ideas
5. **Prioritize** - Add to roadmap based on impact and effort
6. **Execute** - Build, test, launch
---
**This document is a living ideas repository. Add new ideas as they come up during team brainstorms, customer conversations, or competitive analysis.**
**Last Updated**: February 8, 2026
**Contributors**: Planning Session with Claude
**Status**: Ideation - Not Yet Planned

923
KASM_AND_MULTITENANCY.md Normal file
View File

@@ -0,0 +1,923 @@
# Kasm Workspaces & Multi-Tenancy Implementation
## Overview
This document details the implementation plan for:
1. **Kasm Workspaces** - Cloud desktop/workspace service with hourly billing
2. **Multi-Tenancy** - White-label reseller platform using Tenancy for Laravel
---
## Part 1: Kasm Workspaces Integration
### What is Kasm Workspaces?
Kasm Workspaces provides streaming containerized apps and desktops to end-users. It's perfect for:
- **Developer Workspaces**: Pre-configured dev environments (VS Code, IDEs, terminals)
- **Business Workspaces**: Office apps, browsers, secure remote work environments
**Official Docs**: https://docs.kasm.com/
**Developer API**: https://docs.kasm.com/docs/latest/developers/developer_api/
### Service Offerings
| Workspace Type | Use Case | Target Customers |
|----------------|----------|------------------|
| **Developer Basic** | 2 vCPU, 4GB RAM, Linux with VS Code | Freelance developers, students |
| **Developer Pro** | 4 vCPU, 8GB RAM, multiple IDEs, Docker | Professional developers, small teams |
| **Developer Enterprise** | 8 vCPU, 16GB RAM, full dev stack | Development teams, agencies |
| **Business Basic** | 2 vCPU, 4GB RAM, Browser + Office apps | Remote workers, contractors |
| **Business Pro** | 4 vCPU, 8GB RAM, Full office suite | Business users, managers |
| **Business Enterprise** | 8 vCPU, 16GB RAM, Custom apps | Executives, power users |
### Provisioning Strategy
**Fully Automated Provisioning**
1. Customer selects workspace type and template
2. Payment processed (either subscription or credits added)
3. Kasm API called to create workspace
4. Workspace URL and credentials sent via email
5. Customer can access workspace immediately
### Kasm API Integration
#### Key API Endpoints
```http
POST /api/public/create_workspace
Parameters:
- workspace_type (developer_basic, business_pro, etc.)
- user_id
- session_duration (optional)
Response:
{
"workspace_id": "abc-123",
"access_url": "https://kasm.ezscale.cloud/workspace/abc-123",
"username": "user@email.com",
"password": "generated_password"
}
POST /api/public/destroy_workspace
Parameters:
- workspace_id
GET /api/public/workspace_status
Parameters:
- workspace_id
Response:
{
"status": "running",
"uptime_seconds": 3600,
"cpu_usage_percent": 45,
"ram_usage_mb": 2048
}
POST /api/public/stop_workspace
POST /api/public/start_workspace
```
#### Authentication
- API Key authentication via headers
- `X-API-Key: <key>` and `X-API-Secret: <secret>`
- Keys generated in Kasm admin panel
### Database Schema
```sql
kasm_workspaces table:
├── id
├── user_id
├── service_id (links to main services table)
├── workspace_type (developer_basic, business_pro, etc.)
├── kasm_workspace_id (Kasm's internal ID)
├── access_url
├── username (workspace login)
├── password_encrypted
├── status (provisioning, running, stopped, terminated)
├── vcpu (2, 4, 8)
├── ram_mb (4096, 8192, 16384)
├── template_name (Ubuntu with VS Code, Windows 11 Business, etc.)
├── created_at
├── provisioned_at
├── last_started_at
├── last_stopped_at
├── terminated_at
kasm_usage_sessions table:
├── id
├── kasm_workspace_id
├── started_at
├── stopped_at (nullable - ongoing session)
├── duration_seconds (calculated)
├── duration_billable_seconds (rounded to 15-min increments)
├── cost_per_hour (rate at time of use)
├── total_cost (duration_billable_seconds / 3600 * cost_per_hour)
├── invoice_id (nullable - which invoice this was billed on)
├── created_at
kasm_workspace_templates table:
├── id
├── name (Ubuntu 22.04 + VS Code)
├── description
├── workspace_type (developer, business)
├── kasm_template_id (Kasm's image ID)
├── icon_url
├── vcpu_default
├── ram_mb_default
├── preinstalled_apps (JSON array)
├── status (active, deprecated)
├── sort_order
```
### Hourly Billing Model
#### Billing Calculation
- **15-minute increments** (round up)
- Examples:
- 8 minutes = 15 minutes = $0.05 (if $0.20/hour)
- 22 minutes = 30 minutes = $0.10
- 1 hour 5 minutes = 1 hour 15 minutes = $0.25
#### Pricing Structure
| Workspace Type | vCPU | RAM | Price per Hour |
|----------------|------|-----|----------------|
| Developer Basic | 2 | 4GB | $0.15 |
| Developer Pro | 4 | 8GB | $0.30 |
| Developer Enterprise | 8 | 16GB | $0.60 |
| Business Basic | 2 | 4GB | $0.20 |
| Business Pro | 4 | 8GB | $0.40 |
| Business Enterprise | 8 | 16GB | $0.80 |
**Note**: Pricing subject to adjustment based on Kasm licensing costs and infrastructure overhead.
#### Hybrid Billing Approach
- **Real-time tracking**: Dashboard shows current running cost
- **Monthly invoicing**: All usage invoiced at end of billing cycle
- **Running total**: Customer sees "Current month usage: $47.35" in real-time
- **Low balance alerts**: Warn when usage approaching credit limit
### Implementation Flow
#### 1. Customer Orders Workspace
```php
// routes/web.php
Route::post('/kasm/order', [KasmController::class, 'createOrder'])
->middleware(['auth', 'verified']);
// app/Http/Controllers/KasmController.php
public function createOrder(Request $request)
{
$plan = Plan::findOrFail($request->plan_id);
// Validate customer has credits or payment method
if ($user->account_credits < 5.00 && !$user->hasPaymentMethod()) {
return back()->with('error', 'Add credits or payment method first');
}
// Create service record
$service = Service::create([
'user_id' => $user->id,
'plan_id' => $plan->id,
'service_type' => 'kasm_workspace',
'status' => 'provisioning',
]);
// Queue provisioning job
ProvisionKasmWorkspace::dispatch($service);
return redirect()->route('services.show', $service)
->with('success', 'Workspace is being provisioned...');
}
```
#### 2. Provisioning Job
```php
// app/Jobs/ProvisionKasmWorkspace.php
class ProvisionKasmWorkspace implements ShouldQueue
{
public function handle()
{
$kasmService = app(KasmProvisioningService::class);
try {
// Call Kasm API to create workspace
$result = $kasmService->createWorkspace([
'workspace_type' => $this->service->plan->kasm_workspace_type,
'vcpu' => $this->service->plan->vcpu,
'ram_mb' => $this->service->plan->ram_mb,
'template' => $this->service->plan->kasm_template_id,
]);
// Store workspace details
KasmWorkspace::create([
'service_id' => $this->service->id,
'user_id' => $this->service->user_id,
'workspace_type' => $this->service->plan->kasm_workspace_type,
'kasm_workspace_id' => $result['workspace_id'],
'access_url' => $result['access_url'],
'username' => $result['username'],
'password_encrypted' => encrypt($result['password']),
'status' => 'running',
'vcpu' => $this->service->plan->vcpu,
'ram_mb' => $this->service->plan->ram_mb,
'provisioned_at' => now(),
'last_started_at' => now(),
]);
// Start usage session
KasmUsageSession::create([
'kasm_workspace_id' => $workspace->id,
'started_at' => now(),
'cost_per_hour' => $this->service->plan->price_per_hour,
]);
// Update service status
$this->service->update([
'status' => 'active',
'provisioned_at' => now(),
]);
// Send email with credentials
Mail::to($this->service->user)->send(
new KasmWorkspaceProvisioned($workspace)
);
} catch (\Exception $e) {
// Handle provisioning failure
Log::error('Kasm provisioning failed', [
'service_id' => $this->service->id,
'error' => $e->getMessage(),
]);
$this->service->update(['status' => 'failed']);
// Alert admin via Discord
app(DiscordNotificationService::class)->sendAlert([
'title' => 'Kasm Provisioning Failed',
'message' => "Service #{$this->service->id} failed to provision",
'error' => $e->getMessage(),
]);
}
}
}
```
#### 3. Usage Tracking
```php
// app/Console/Commands/TrackKasmUsage.php
// Run every 15 minutes via cron
class TrackKasmUsage extends Command
{
public function handle()
{
$activeWorkspaces = KasmWorkspace::where('status', 'running')->get();
foreach ($activeWorkspaces as $workspace) {
// Check if workspace is still running via API
$status = app(KasmProvisioningService::class)
->getWorkspaceStatus($workspace->kasm_workspace_id);
if ($status['status'] === 'stopped') {
// Workspace was stopped, close usage session
$session = KasmUsageSession::where('kasm_workspace_id', $workspace->id)
->whereNull('stopped_at')
->first();
if ($session) {
$session->update([
'stopped_at' => now(),
'duration_seconds' => now()->diffInSeconds($session->started_at),
]);
// Calculate billable duration (round to 15-min increments)
$minutes = ceil($session->duration_seconds / 60);
$billableMinutes = ceil($minutes / 15) * 15;
$billableSeconds = $billableMinutes * 60;
$session->update([
'duration_billable_seconds' => $billableSeconds,
'total_cost' => ($billableSeconds / 3600) * $session->cost_per_hour,
]);
}
$workspace->update(['status' => 'stopped']);
}
}
}
}
```
#### 4. Monthly Billing
```php
// app/Console/Commands/BillKasmUsage.php
// Run monthly on billing cycle date
class BillKasmUsage extends Command
{
public function handle()
{
$users = User::has('kasmWorkspaces')->get();
foreach ($users as $user) {
// Get unbilled usage sessions
$sessions = KasmUsageSession::whereHas('workspace', function ($q) use ($user) {
$q->where('user_id', $user->id);
})
->whereNull('invoice_id')
->where('stopped_at', '!=', null)
->get();
if ($sessions->isEmpty()) continue;
$totalCost = $sessions->sum('total_cost');
// Create invoice
$invoice = Invoice::create([
'user_id' => $user->id,
'total' => $totalCost,
'currency' => 'USD',
'due_date' => now()->addDays(7),
'description' => 'Kasm Workspace Usage - ' . now()->format('F Y'),
]);
// Add line items
foreach ($sessions as $session) {
InvoiceItem::create([
'invoice_id' => $invoice->id,
'description' => sprintf(
'%s - %s (%d minutes @ $%s/hour)',
$session->workspace->workspace_type,
$session->started_at->format('M d, Y'),
$session->duration_billable_seconds / 60,
number_format($session->cost_per_hour, 2)
),
'amount' => $session->total_cost,
'quantity' => 1,
]);
// Mark session as billed
$session->update(['invoice_id' => $invoice->id]);
}
// Send invoice email
Mail::to($user)->send(new InvoiceGenerated($invoice));
// Charge payment method
if ($user->hasDefaultPaymentMethod()) {
try {
$payment = $user->charge($totalCost * 100, $user->defaultPaymentMethod());
$invoice->update(['paid_at' => now()]);
} catch (\Exception $e) {
// Payment failed - send notification
Mail::to($user)->send(new PaymentFailed($invoice));
}
}
}
}
}
```
### Customer Dashboard Features
#### Workspace Management
- **Start/Stop Controls**: Customer can start/stop workspace from dashboard
- **Current Session Timer**: "Running for 2 hours 37 minutes - $0.50"
- **Monthly Usage Summary**: "This month: $47.35 (23.5 hours)"
- **Session History**: List of all sessions with durations and costs
- **Workspace Access**: One-click button to launch workspace in new tab
#### Running Cost Indicator
```vue
<!-- resources/js/Pages/Services/KasmWorkspace.vue -->
<template>
<div class="workspace-status">
<div v-if="workspace.status === 'running'" class="running">
<Icon name="circle-dot" class="text-green-500 animate-pulse" />
<span>Running for {{ runningDuration }}</span>
<span class="text-lg font-bold">${{ currentCost }}</span>
<button @click="stopWorkspace">Stop Workspace</button>
</div>
<div v-else class="stopped">
<Icon name="circle" class="text-gray-400" />
<span>Stopped</span>
<button @click="startWorkspace">Start Workspace</button>
</div>
<div class="usage-summary">
<h3>This Month's Usage</h3>
<p class="text-2xl">${{ monthlyTotal }}</p>
<p class="text-sm text-gray-600">{{ totalHours }} hours</p>
</div>
</div>
</template>
<script setup>
import { ref, computed, onMounted } from 'vue'
import { router } from '@inertiajs/vue3'
const props = defineProps(['workspace'])
const runningDuration = ref('0m')
const currentCost = ref(0)
// Update every minute if running
let interval
onMounted(() => {
if (props.workspace.status === 'running') {
updateRunningCost()
interval = setInterval(updateRunningCost, 60000) // Every minute
}
})
function updateRunningCost() {
const started = new Date(props.workspace.last_started_at)
const now = new Date()
const minutes = Math.floor((now - started) / 60000)
const hours = Math.floor(minutes / 60)
const mins = minutes % 60
runningDuration.value = hours > 0 ? `${hours}h ${mins}m` : `${mins}m`
// Calculate cost (round to 15-min increments)
const billableMinutes = Math.ceil(minutes / 15) * 15
currentCost.value = ((billableMinutes / 60) * props.workspace.cost_per_hour).toFixed(2)
}
function startWorkspace() {
router.post(`/kasm/${props.workspace.id}/start`)
}
function stopWorkspace() {
router.post(`/kasm/${props.workspace.id}/stop`)
}
</script>
```
---
## Part 2: Multi-Tenancy (White-Label Resellers)
### What is Multi-Tenancy?
Allowing resellers to run their own branded billing platform using your infrastructure. Each reseller (tenant) has:
- Their own customers
- Their own branding (logo, colors, domain)
- Their own pricing
- Isolated database
### Tenancy for Laravel Package
**Package**: https://tenancyforlaravel.com/
**Documentation**: https://tenancyforlaravel.com/docs/v3/
**Key Features**:
- Automatic tenant identification (by domain, subdomain, or path)
- Database per tenant (complete isolation)
- Tenant-aware caching, filesystems, queues
- Easy migrations across all tenants
- Central app + tenant apps architecture
### Architecture
#### Central Application
- **Domain**: ezscale.cloud (your main application)
- **Purpose**: Manage resellers (tenants), global settings, wholesale billing
- **Database**: `ezscale_central` (stores tenant list, domains, configs)
#### Tenant Applications
- **Domains**: `reseller1.com`, `reseller2.hosting`, `custom-domain.net`
- **Purpose**: Each reseller's branded billing platform
- **Databases**: `tenant_reseller1`, `tenant_reseller2`, `tenant_custom`
### Database Structure
#### Central Database (`ezscale_central`)
```sql
tenants table:
├── id
├── name (Reseller Company Name)
├── slug (reseller1, reseller2)
├── database_name (tenant_reseller1)
├── domain (reseller1.com, custom-domain.net)
├── status (active, suspended, trial)
├── owner_email
├── owner_name
├── created_at
├── trial_ends_at (nullable)
├── suspended_at (nullable)
tenant_domains table:
├── id
├── tenant_id
├── domain (reseller1.com, reseller1.ezscale.cloud, custom-domain.net)
├── type (primary, alias)
├── ssl_status (pending, active, failed)
├── verified_at
├── created_at
tenant_billing table:
├── id
├── tenant_id
├── plan_id (reseller tier: basic, pro, enterprise)
├── wholesale_discount_percent (e.g., 30% off retail prices)
├── monthly_fee (platform fee - e.g., $99/month)
├── commission_percent (if commission-based instead of wholesale)
├── billing_cycle_day (1-28)
├── next_billing_date
├── status (active, past_due, cancelled)
tenant_branding table:
├── id
├── tenant_id
├── logo_url
├── favicon_url
├── primary_color (#3B82F6)
├── secondary_color
├── company_name
├── support_email
├── support_phone
├── from_email (noreply@reseller.com)
├── from_name (Reseller Hosting)
├── custom_css (nullable - advanced branding)
```
#### Tenant Databases (e.g., `tenant_reseller1`)
Each tenant gets a complete copy of the main application schema:
- `users` (reseller's customers)
- `plans` (reseller's custom pricing)
- `subscriptions`
- `invoices`
- `services`
- `kasm_workspaces`
- ... all other tables from main schema
**Key difference**: Tenant plans reference wholesale prices in central database, but show custom prices to customers.
### Installation & Setup
```bash
# Install Tenancy for Laravel
composer require stancl/tenancy
# Publish config and migrations
php artisan vendor:publish --provider='Stancl\Tenancy\TenancyServiceProvider'
# Run central migrations
php artisan migrate
# Configure tenancy
# config/tenancy.php
return [
'tenant_model' => \App\Models\Tenant::class,
'id_generator' => \Stancl\Tenancy\UUIDGenerator::class,
'database' => [
'prefix' => 'tenant_',
'template_tenant_connection' => 'mysql',
],
'bootstrappers' => [
\Stancl\Tenancy\Bootstrappers\DatabaseTenancyBootstrapper::class,
\Stancl\Tenancy\Bootstrappers\CacheTenancyBootstrapper::class,
\Stancl\Tenancy\Bootstrappers\FilesystemTenancyBootstrapper::class,
\Stancl\Tenancy\Bootstrappers\QueueTenancyBootstrapper::class,
],
];
```
### Creating a Reseller (Tenant)
```php
// app/Http/Controllers/Admin/ResellerController.php
public function store(Request $request)
{
$validated = $request->validate([
'name' => 'required|string',
'email' => 'required|email|unique:tenants,owner_email',
'domain' => 'required|string|unique:tenant_domains,domain',
]);
// Create tenant
$tenant = Tenant::create([
'name' => $validated['name'],
'slug' => Str::slug($validated['name']),
'owner_email' => $validated['email'],
]);
// Create domain
$tenant->domains()->create([
'domain' => $validated['domain'],
'type' => 'primary',
]);
// Run migrations for tenant database
$tenant->run(function () {
Artisan::call('migrate', ['--database' => 'tenant', '--force' => true]);
// Seed initial data (plans, roles, etc.)
Artisan::call('db:seed', ['--class' => 'TenantSeeder']);
});
// Set up branding defaults
TenantBranding::create([
'tenant_id' => $tenant->id,
'company_name' => $validated['name'],
'primary_color' => '#3B82F6',
'support_email' => $validated['email'],
]);
// Send welcome email to reseller
Mail::to($validated['email'])->send(new ResellerWelcome($tenant));
return redirect()->route('admin.resellers.index')
->with('success', 'Reseller created successfully!');
}
```
### Tenant Identification (Automatic)
```php
// routes/web.php (Central app routes)
Route::get('/', [HomeController::class, 'index']);
Route::get('/admin/resellers', [Admin\ResellerController::class, 'index'])
->middleware(['auth', 'admin']);
// routes/tenant.php (Tenant-specific routes)
Route::middleware('tenant')->group(function () {
// These routes run within tenant context
Route::get('/', [Tenant\DashboardController::class, 'index']);
Route::get('/services', [Tenant\ServiceController::class, 'index']);
Route::post('/kasm/order', [Tenant\KasmController::class, 'createOrder']);
// ... all customer-facing routes
});
// Middleware automatically identifies tenant by domain
// If request is to reseller1.com → loads tenant_reseller1 database
// If request is to ezscale.cloud → uses central database
```
### Reseller Pricing Control
```php
// Tenant database: plans table
// Reseller can set any price they want
CREATE TABLE plans (
id INT PRIMARY KEY,
name VARCHAR(255),
description TEXT,
price DECIMAL(10, 2), -- Reseller's customer price
wholesale_price DECIMAL(10, 2), -- What reseller pays EZSCALE
service_type VARCHAR(50),
-- ... other fields
);
// Example:
// VPS Basic
// - Wholesale price (you charge reseller): $8/month
// - Reseller's price (they charge customer): $15/month
// - Reseller's profit: $7/month per customer
// When customer subscribes:
// 1. Customer pays reseller $15
// 2. Reseller pays you $8 (via wholesale invoice)
// 3. Reseller keeps $7 profit
```
### Wholesale Billing (Billing Resellers)
```php
// app/Console/Commands/BillResellers.php
// Run monthly to bill resellers for their customer usage
class BillResellers extends Command
{
public function handle()
{
$tenants = Tenant::where('status', 'active')->get();
foreach ($tenants as $tenant) {
// Switch to tenant database
$tenant->run(function () use ($tenant) {
// Count active subscriptions
$subscriptions = Subscription::where('status', 'active')->get();
$wholesaleTotal = 0;
foreach ($subscriptions as $subscription) {
$plan = Plan::find($subscription->plan_id);
$wholesaleTotal += $plan->wholesale_price;
}
// Add platform fee
$platformFee = TenantBilling::where('tenant_id', $tenant->id)
->value('monthly_fee');
$totalDue = $wholesaleTotal + $platformFee;
// Create wholesale invoice in CENTRAL database
tenancy()->end(); // Switch back to central
WholesaleInvoice::create([
'tenant_id' => $tenant->id,
'platform_fee' => $platformFee,
'usage_charges' => $wholesaleTotal,
'total' => $totalDue,
'due_date' => now()->addDays(7),
]);
// Email reseller
Mail::to($tenant->owner_email)->send(
new ResellerInvoice($tenant, $totalDue)
);
});
}
}
}
```
### Reseller Dashboard (Central App)
Resellers log into ezscale.cloud/reseller to:
- View their wholesale invoices
- See customer count and revenue
- Manage branding (logo, colors)
- View usage statistics
- Configure pricing for their plans
- Add/manage their custom domains
### Branding Customization
```php
// app/Http/Controllers/Reseller/BrandingController.php
public function update(Request $request)
{
$tenant = Auth::user()->tenant;
$validated = $request->validate([
'logo' => 'nullable|image|max:2048',
'primary_color' => 'required|string',
'company_name' => 'required|string',
'support_email' => 'required|email',
]);
if ($request->hasFile('logo')) {
$logoPath = $request->file('logo')->store('tenant_logos', 's3');
$validated['logo_url'] = Storage::disk('s3')->url($logoPath);
}
$tenant->branding()->update($validated);
return back()->with('success', 'Branding updated!');
}
```
### Loading Tenant Branding
```php
// app/Http/Middleware/InjectTenantBranding.php
public function handle($request, $next)
{
if (tenancy()->initialized) {
$branding = TenantBranding::where('tenant_id', tenant('id'))->first();
// Share branding with all views
View::share('branding', $branding);
// Inject CSS variables
if ($branding) {
$customCss = "
:root {
--primary-color: {$branding->primary_color};
--secondary-color: {$branding->secondary_color};
}
";
View::share('customCss', $customCss);
}
}
return $next($request);
}
```
```blade
<!-- resources/views/layouts/tenant.blade.php -->
<!DOCTYPE html>
<html>
<head>
<title>{{ $branding->company_name ?? 'EZSCALE Hosting' }}</title>
<link rel="icon" href="{{ $branding->favicon_url ?? asset('favicon.ico') }}">
@if(isset($customCss))
<style>{!! $customCss !!}</style>
@endif
@vite(['resources/css/app.css', 'resources/js/app.js'])
</head>
<body>
<nav>
<img src="{{ $branding->logo_url ?? asset('logo.png') }}" alt="Logo">
<span>{{ $branding->company_name }}</span>
</nav>
@yield('content')
<footer>
<p>Support: {{ $branding->support_email }}</p>
</footer>
</body>
</html>
```
---
## Integration Points
### Kasm + Multi-Tenancy
- Each tenant (reseller) can offer Kasm workspaces
- Resellers set their own Kasm pricing
- Usage tracked per tenant database
- Wholesale billing aggregates all tenant usage
### Database Structure
```
Central DB (ezscale_central)
├── tenants
├── tenant_domains
├── tenant_billing
└── wholesale_invoices
Tenant DB (tenant_reseller1)
├── users (reseller's customers)
├── subscriptions
├── kasm_workspaces
├── kasm_usage_sessions
└── invoices (customer invoices)
```
---
## Implementation Phases
### Phase 12: Kasm Workspaces (New Phase)
- [ ] Research Kasm licensing (per named user vs concurrent session)
- [ ] Set up Kasm Workspaces instance
- [ ] Create Kasm API integration service
- [ ] Build workspace provisioning automation
- [ ] Implement usage tracking (15-min increments)
- [ ] Build workspace management UI
- [ ] Implement start/stop controls
- [ ] Create workspace templates (dev + business)
- [ ] Build monthly usage billing
- [ ] Test end-to-end workflow
### Phase 13: Multi-Tenancy (New Phase)
- [ ] Install Tenancy for Laravel package
- [ ] Configure tenant identification (domain-based)
- [ ] Create central reseller management UI
- [ ] Build tenant creation workflow
- [ ] Implement automatic tenant migrations
- [ ] Build branding customization system
- [ ] Create wholesale billing system
- [ ] Build reseller dashboard
- [ ] Test multi-domain SSL (Let's Encrypt)
- [ ] Test tenant isolation thoroughly
- [ ] Create reseller onboarding documentation
---
## Open Questions
- [ ] **Kasm Licensing**: Which Kasm license tier (per named user vs concurrent)? Cost per user?
- [ ] **Kasm Infrastructure**: Self-hosted Kasm server or Kasm cloud? If self-hosted, hardware requirements?
- [ ] **Reseller Trials**: Should resellers get trial period? How long?
- [ ] **Reseller Pricing**: Fixed platform fee ($99/month) or percentage of revenue?
- [ ] **Minimum Customers**: Require minimum customer count before reseller can launch?
- [ ] **Support Responsibility**: Who handles tenant customer support - you or reseller?
---
## Summary
This document provides comprehensive implementation plans for:
1. **Kasm Workspaces Integration**
- Fully automated provisioning
- Hourly billing with 15-minute increments
- Real-time usage tracking
- Developer and Business workspace types
- Complete API integration
2. **Multi-Tenancy for Resellers**
- Database-per-tenant isolation
- Full white-label branding
- Custom domain support
- Reseller pricing control
- Wholesale billing system
Both features significantly expand EZSCALE's service offerings and create new revenue streams through workspace hosting and reseller partnerships.
**References**:
- [Kasm Workspaces Documentation](https://docs.kasm.com/)
- [Kasm Developer API](https://docs.kasm.com/docs/latest/developers/developer_api/)
- [Tenancy for Laravel](https://tenancyforlaravel.com/)
- [Multi-Database Tenancy Docs](https://tenancyforlaravel.com/docs/v3/multi-database-tenancy/)

604
PROJECT_DEVELOPMENT.md Normal file
View File

@@ -0,0 +1,604 @@
# PROJECT_DEVELOPMENT.md - EZSCALE Site Architecture & Development Plan
## 1. Project Goal
Replace WHMCS with a custom Laravel 12 application for managing EZSCALE Hosting's VPS, Dedicated Server, Web Hosting, and Game Server business. The new platform must handle customer management, billing/subscriptions, automated provisioning, bandwidth monitoring, and comprehensive admin controls.
## 2. Infrastructure Overview
### Current EZSCALE Stack
- **VPS Platform:** VirtFusion (KVM/QEMU hypervisor stack)
- **Game Servers:** Pterodactyl Panel
- **Dedicated Servers:** SynergyCP
- **Web Hosting:** Enhance (https://enhance.com/)
- **Container Management:** Portainer (for BFACP deployment)
- **Support System:** SupportPal (ticketing)
- **Network:** Juniper switches with VLANs (dedicated customers, corporate, hypervisors)
- **Bandwidth Monitoring:** ElastiFlow (NetFlow/sFlow collector)
### Domain Structure
- **ezscale.cloud** — Marketing frontend, product catalog, public pages
- **account.ezscale.cloud** — Customer dashboard, service management, billing
- **admin.ezscale.cloud** — Admin panel (behind Cloudflare Zero Trust + passkeys)
### Hosting
- **Application Hosting:** EZSCALE's own infrastructure
- **Database:** MySQL 8.x with full redundancy (multi-region replication, automated backups, DR plan)
- **Caching/Queue:** Redis
- **Email Service:** Mailgun or SendGrid
## 3. Application Architecture
### High-Level Architecture
```
┌──────────────────────────────────────────────────────────────────┐
│ ezscale.cloud │
│ Marketing Site + Product Catalog (Laravel) │
└──────────────────────────────────────────────────────────────────┘
│
┌────────────┴────────────┐
│ │
┌───────────────────▼─────────┐ ┌───────────▼──────────────────────┐
│ account.ezscale.cloud │ │ admin.ezscale.cloud │
│ Customer Dashboard │ │ Admin Panel │
│ (Vue 3 + Inertia.js) │ │ (Cloudflare Zero Trust) │
└───────────────┬──────────────┘ └──────────┬───────────────────────┘
│ │
┌───────────────┴────────────────────────────┴───────────────────────┐
│ Laravel 12 Core │
│ ┌──────────┐ ┌──────────┐ ┌──────────────┐ ┌───────────────────┐ │
│ │ Auth │ │ Billing │ │ Provisioning │ │ Bandwidth │ │
│ │ Fortify │ │ Cashier │ │ Services │ │ Monitoring │ │
│ │ Passport │ │ Stripe │ │ VirtFusion │ │ ElastiFlow │ │
│ │ │ │ PayPal │ │ Pterodactyl │ │ Integration │ │
│ │ │ │ │ │ SynergyCP │ │ │ │
│ │ │ │ │ │ Enhance │ │ │ │
│ └──────────┘ └──────────┘ └──────────────┘ └───────────────────┘ │
│ ┌──────────┐ ┌──────────┐ ┌──────────────┐ ┌───────────────────┐ │
│ │SupportPal│ │Analytics │ │ Customer │ │ Admin Tools │ │
│ │Integration│ │Dashboard │ │ API │ │ Full Control │ │
│ │SSO+Tickets│ │MRR/Churn │ │ │ │ │ │
│ └──────────┘ └──────────┘ └──────────────┘ └───────────────────┘ │
├─────────────────────────────────────────────────────────────────────┤
│ MySQL 8.x (Multi-region) │ Redis (Queue/Cache/Session) │
└─────────────────────────────────────────────────────────────────────┘
│ │
┌────┴────────┬──────────┬───────────┬───┴────┬─────────────┐
│ │ │ │ │ │
VirtFusion Pterodactyl SynergyCP Enhance SupportPal ElastiFlow
API API API API API API
```
## 4. Key Design Decisions
### Payment & Billing (DECIDED)
- **Primary Gateway:** Stripe via Laravel Cashier v16 (~80%+ of customers)
- **Secondary Gateway:** PayPal via `srmklive/laravel-paypal` (~20% recurring subscriptions)
- **Tax:** To be decided (TaxJar/Avalara or manual rates)
- **Multi-Currency:** Full support (EUR, GBP, USD, etc.) via Stripe
- **Invoicing:** Full-featured PDF generation, custom numbering, multi-currency, email delivery
- **Payment Methods:** Customers can manage multiple payment methods per account
- **Coupons:** Full coupon system (percentage, fixed amount, trial extensions, usage limits, expiry)
- **Billing Architecture:** `BillingServiceInterface` abstracts Stripe and PayPal for gateway-agnostic code
### Frontend & Auth (DECIDED)
- **Stack:** Vue 3 + Inertia.js + Tailwind CSS (Laravel 12 Vue starter kit)
- **UI Theme:** **Vuexy** VueJS + Laravel Admin Dashboard Template
- Purchase: https://themeforest.net/item/vuexy-vuejs-html-laravel-admin-dashboard-template/23328599
- Demo: https://pixinvent.com/vuexy-vuejs-laravel-admin-template/
- Features: Pre-built admin components, charts, forms, tables, authentication pages, responsive design
- Source files will be integrated when development begins
- **Auth:** Laravel Fortify (headless backend) + Vuexy-styled Vue/Inertia auth pages
- **2FA:** Required for admins (passkeys preferred), encouraged for customers (TOTP/Authenticator)
- **SSO:** Laravel Passport OAuth2 server for future integrations
- **API:** RESTful API for both customers (service management) and admins
### Provisioning (DECIDED - Fully Automated)
All service provisioning is **fully automated** via API on successful payment:
| Service Type | Platform | Automation |
|--------------|----------|------------|
| VPS | VirtFusion API | Payment succeeds → API creates VPS → credentials emailed |
| Game Servers | Pterodactyl API | Payment succeeds → API creates server → credentials emailed |
| Dedicated Servers | SynergyCP API | Payment succeeds → API provisions (if hardware available) → credentials emailed |
| Web Hosting | Enhance API | Payment succeeds → API creates hosting account → credentials emailed |
**Note:** Dedicated servers may require semi-automation (admin assigns hardware if inventory limited).
### Panel Integration (DECIDED)
- **Pterodactyl & SynergyCP:** Separate login credentials (no SSO)
- **Dashboard Integration:** Full integration - Laravel dashboard shows:
- Server status (online/offline)
- Resource usage (CPU, RAM, disk, bandwidth)
- Basic controls (restart, power on/off via API)
- Links to panels for advanced management
- **Enhance:** Full integration for hosting account status and resource usage
### Bandwidth Monitoring (DECIDED)
- **Collection:** NetFlow/sFlow via ElastiFlow (Elastic-based flow collector)
- **Integration:** Laravel queries ElastiFlow API/database for bandwidth data
- **Display:** Real-time bandwidth graphs in customer dashboard
- **Billing:** Automatic overage billing at end of billing cycle
- **Alerts:** Multi-threshold warnings (75%, 90%, 100% of quota) via email + Discord webhook
- **No Add-ons:** Automatic overage billing only (no one-time bandwidth add-ons)
### Support Integration (DECIDED)
- **System:** SupportPal (external ticketing system)
- **Integration Level:** Full integration
- SSO for seamless access
- View recent tickets in billing dashboard
- Create tickets from billing panel via SupportPal API
- Full ticket history accessible to customers
- **Discord:** Admin notifications via webhook (new orders, failures, cancellations, high revenue)
### Customer Features (DECIDED)
- **Dashboard Layout:** Service overview (active services, next invoice, recent tickets, quick actions)
- **Self-Service:** Full self-service upgrades/downgrades with automatic proration
- **Cancellation:** Self-service cancellation with optional survey (service remains active until period end)
- **Payment Methods:** Manage multiple cards/PayPal accounts, set default per service
### Admin Panel (DECIDED)
- **Access Security:** Cloudflare Zero Trust + 2FA (passkeys preferred)
- **Control Level:** Full control over all customer services
- Provision, suspend, terminate, modify services
- View/edit customer accounts
- Invoice management, payment processing
- Analytics dashboard (MRR, ARR, churn, revenue trends, popular plans)
- **Suspension Policy:** Automatic suspension X days past due → terminate Y days later
### Analytics & Reporting (DECIDED)
- **Comprehensive analytics dashboard:**
- Revenue trends (daily, monthly, yearly)
- MRR (Monthly Recurring Revenue) and ARR (Annual Recurring Revenue)
- Churn rate and customer growth
- Plan popularity and conversion rates
- Outstanding invoices and overdue accounts
### Deployment & CI/CD (DECIDED)
- **CI/CD:** GitHub Actions pipeline
- Tests run on push
- Auto-deploy to staging environment
- Manual approval for production deployment
- **Environments:** Full staging environment (staging.account.ezscale.cloud with separate database)
## 5. Database Schema (Core Tables)
### Users & Auth
```
users
├── id, name, email, email_verified_at, password
├── status (active, suspended, banned)
├── phone, company
├── two_factor_secret, two_factor_recovery_codes
├── passkey_credentials (JSON for WebAuthn)
├── timestamps
user_profiles
├── id, user_id
├── billing_address (line1, line2, city, state, zip, country)
├── shipping_address (line1, line2, city, state, zip, country)
├── tax_id, tax_exempt
├── company_name, company_vat
├── notes (admin notes)
├── timestamps
roles (via spatie/laravel-permission)
├── id, name (admin, customer), guard_name, timestamps
permissions (via spatie/laravel-permission)
├── id, name, guard_name, timestamps
audit_logs
├── id, user_id, admin_id (nullable)
├── action (login, logout, service_provisioned, service_suspended, payment_failed, etc.)
├── resource_type, resource_id
├── ip_address, user_agent
├── changes (JSON - before/after state)
├── timestamps
```
### Billing
```
plans
├── id, name, slug, description
├── service_type (vps, dedicated, hosting, game_server)
├── price, currency, billing_cycle (monthly, quarterly, annual, hourly)
├── stripe_price_id, paypal_plan_id
├── features (JSON - RAM, CPU, disk, bandwidth, etc.)
├── stock_quantity (nullable - for limited dedicated server inventory)
├── status (active, hidden, archived)
├── sort_order
├── timestamps
subscriptions (extended from Cashier)
├── id, user_id, plan_id
├── gateway (stripe, paypal)
├── gateway_subscription_id
├── gateway_customer_id
├── gateway_price_id
├── status (active, past_due, cancelled, paused, trialing)
├── trial_ends_at, current_period_start, current_period_end
├── cancelled_at, ends_at
├── timestamps
subscription_items (Cashier-managed)
├── id, subscription_id, stripe_id, stripe_product, stripe_price
├── quantity, timestamps
invoices (extended from Cashier)
├── id, subscription_id, user_id
├── gateway (stripe, paypal), gateway_invoice_id
├── number (custom invoice numbering)
├── total, tax, currency, status
├── invoice_pdf (path to generated PDF)
├── due_date, paid_at
├── timestamps
invoice_items
├── id, invoice_id
├── description, amount, quantity
├── timestamps
payment_transactions
├── id, user_id, subscription_id (nullable), invoice_id (nullable)
├── gateway (stripe, paypal), gateway_transaction_id
├── amount, currency, status (succeeded, failed, refunded, pending)
├── payment_method (card, paypal, bank_transfer)
├── description, metadata (JSON)
├── timestamps
coupons
├── id, code, type (percentage, fixed_amount)
├── value, currency (for fixed_amount)
├── applies_to (all, specific_plans - JSON array of plan IDs)
├── max_uses, times_used
├── expires_at
├── timestamps
coupon_redemptions
├── id, coupon_id, user_id, subscription_id
├── discount_amount
├── timestamps
```
### Services & Provisioning
```
services
├── id, user_id, subscription_id, plan_id
├── service_type (vps, dedicated, hosting, game_server)
├── platform (virtfusion, pterodactyl, synergycp, enhance)
├── platform_service_id (ID in external system)
├── status (pending, active, suspended, terminated)
├── ipv4_address, ipv6_address
├── hostname, domain
├── credentials (encrypted JSON - username, password, access URLs)
├── provisioned_at, suspended_at, terminated_at
├── auto_renew (boolean)
├── timestamps
provisioning_logs
├── id, service_id, user_id
├── action (create, suspend, unsuspend, terminate, upgrade, downgrade)
├── platform, platform_response (JSON)
├── status (pending, success, failed)
├── error_message
├── admin_id (nullable - if manually triggered)
├── timestamps
bandwidth_usage
├── id, service_id
├── period_start, period_end
├── bytes_in, bytes_out, total_bytes
├── quota_bytes, overage_bytes
├── overage_charge
├── source (elastiflow)
├── timestamps
```
### Support (SupportPal Integration)
```
support_tickets (mirrored from SupportPal via webhooks)
├── id, user_id
├── supportpal_ticket_id
├── subject, status (open, closed, pending)
├── priority (low, medium, high, urgent)
├── last_reply_at
├── timestamps
announcements
├── id, title, content (HTML)
├── type (maintenance, feature, outage)
├── published_at, expires_at
├── timestamps
```
## 6. Key Integrations
### 6.1 VirtFusion API (VPS Provisioning)
**Endpoints needed:**
- `POST /api/vps/create` - Create new VPS instance
- `POST /api/vps/{id}/suspend` - Suspend VPS
- `POST /api/vps/{id}/unsuspend` - Unsuspend VPS
- `DELETE /api/vps/{id}` - Terminate VPS
- `GET /api/vps/{id}/status` - Get VPS status and resource usage
- `POST /api/vps/{id}/reboot` - Reboot VPS
**Provisioning Service:** `App\Services\Provisioning\VirtFusionService`
### 6.2 Pterodactyl API (Game Server Provisioning)
**Endpoints needed:**
- `POST /api/application/servers` - Create server
- `POST /api/application/servers/{id}/suspend` - Suspend
- `POST /api/application/servers/{id}/unsuspend` - Unsuspend
- `DELETE /api/application/servers/{id}` - Delete
- `GET /api/client/servers/{id}/resources` - Resource usage
**Provisioning Service:** `App\Services\Provisioning\PterodactylService`
### 6.3 SynergyCP API (Dedicated Server Provisioning)
**Endpoints needed:**
- `POST /api/server/provision` - Provision dedicated server
- `POST /api/server/{id}/suspend` - Suspend
- `POST /api/server/{id}/unsuspend` - Unsuspend
- `POST /api/server/{id}/terminate` - Terminate
- `GET /api/server/{id}` - Get server details and status
**Provisioning Service:** `App\Services\Provisioning\SynergyCPService`
### 6.4 Enhance API (Web Hosting Provisioning)
**Endpoints needed:**
- `POST /api/orgs/{org}/websites` - Create hosting account
- `PUT /api/orgs/{org}/websites/{id}/suspended` - Suspend
- `DELETE /api/orgs/{org}/websites/{id}` - Delete
- `GET /api/orgs/{org}/websites/{id}` - Get account status
**Provisioning Service:** `App\Services\Provisioning\EnhanceService`
### 6.5 ElastiFlow API (Bandwidth Monitoring)
**Integration approach:**
- Query Elasticsearch indices via REST API
- Aggregate bandwidth by service IP address and time period
- Calculate usage per billing cycle
- Store results in `bandwidth_usage` table
- Scheduled job runs daily to update bandwidth stats
**Service:** `App\Services\Monitoring\BandwidthService`
### 6.6 SupportPal API (Ticket System)
**Endpoints needed:**
- `GET /api/ticket/{id}` - Get ticket details
- `GET /api/ticket/user/{user_id}` - Get user's tickets
- `POST /api/ticket` - Create new ticket
- `POST /api/ticket/{id}/reply` - Reply to ticket
- `GET /api/ticket/{id}/replies` - Get ticket thread
**SSO Implementation:** SupportPal supports SAML or custom SSO - use Laravel Passport tokens
**Service:** `App\Services\Support\SupportPalService`
### 6.7 Email Notifications (Mailgun/SendGrid)
**Laravel Notifications for:**
- Welcome email (account created)
- Email verification
- Invoice generated (with PDF attachment)
- Payment received (receipt)
- Payment failed (with retry instructions)
- Service provisioned (credentials)
- Service suspended (past due payment)
- Service expiring soon (renewal reminder)
- Bandwidth usage alerts (75%, 90%, 100%)
- Bandwidth overage charge (end of cycle)
- Ticket updates (new reply, status change)
### 6.8 Discord Webhooks (Admin Alerts)
**Notifications sent to Discord:**
- New customer signup
- New order / subscription created
- High-value order (e.g., >$500)
- Payment failure
- Service suspension
- Service cancellation
- System errors / provisioning failures
- Security alerts (admin login failures, etc.)
## 7. Security Architecture
### Authentication
- **Customer Auth:** Email + password (bcrypt), optional 2FA (TOTP), passkey support (WebAuthn)
- **Admin Auth:** Email + password + **required** 2FA (passkeys preferred), behind Cloudflare Zero Trust
- **Session Management:** Redis-backed sessions with secure cookies
- **API Auth:** Laravel Sanctum tokens for customer/admin APIs
### Authorization
- **Roles:** `admin` and `customer` via spatie/laravel-permission
- **Policies:** Laravel policies for resource-level authorization (can user view this service?)
- **Admin Actions:** All admin actions logged to `audit_logs` table
- **Admin Impersonation:** Admins can impersonate customers (with audit logging)
### Data Protection
- **Encryption at Rest:** Service credentials, API keys, payment tokens encrypted in database
- **HTTPS Everywhere:** All traffic HTTPS-only, HSTS headers
- **CSRF Protection:** All forms CSRF-protected
- **Rate Limiting:** Login, registration, API endpoints rate-limited
- **Input Validation:** Laravel Form Request classes for all inputs
- **SQL Injection Prevention:** Eloquent ORM + prepared statements
- **XSS Prevention:** Blade/Vue escaping, CSP headers
### Admin Panel Security
- **Cloudflare Zero Trust:** Admin panel behind Zero Trust access control
- **Passkeys/2FA:** Required for all admin accounts
- **IP Logging:** All admin actions logged with IP address
- **Suspicious Activity Alerts:** Discord webhook for failed admin logins
## 8. Development Phases
### Phase 1: Foundation & Core Setup
- Initialize Laravel 12 with Vue + Inertia starter kit
- Configure domains: ezscale.cloud, account.ezscale.cloud, admin.ezscale.cloud
- Set up MySQL with replication, Redis
- Install dependencies: Cashier, Fortify, Passport, PayPal, Spatie
- Create database schema and migrations
- Set up authentication (Fortify + 2FA + passkeys)
- Configure Cloudflare Zero Trust for admin panel
- Set up CI/CD pipeline (GitHub Actions)
### Phase 2: Billing & Subscriptions
- Implement `BillingServiceInterface` (Stripe + PayPal)
- Build plan catalog (VPS, Dedicated, Hosting, Game Server plans)
- Subscription creation and management
- Invoice generation (PDF, custom numbering, multi-currency)
- Payment method management (multiple cards/PayPal per customer)
- Coupon system (creation, redemption, validation)
- Webhook handlers for Stripe and PayPal
- Automatic overage billing for bandwidth
- Tax calculation (TaxJar/Avalara or manual)
### Phase 3: Provisioning Automation
- `ProvisioningServiceInterface` abstraction
- VirtFusion provisioning service
- Pterodactyl provisioning service
- SynergyCP provisioning service
- Enhance provisioning service
- Event-driven provisioning (listen to payment success events)
- Credential generation and secure storage
- Provisioning failure handling and retry logic
### Phase 4: Customer Dashboard (account.ezscale.cloud)
- Service overview dashboard
- Active services list with status and resource usage
- Bandwidth usage graphs (from ElastiFlow)
- Billing history and invoices (PDF download)
- Payment methods management
- Plan upgrades/downgrades (self-service)
- Subscription cancellation (with survey)
- Profile and account settings
- 2FA and passkey setup
### Phase 5: Admin Panel (admin.ezscale.cloud)
- Analytics dashboard (MRR, ARR, churn, revenue trends)
- Customer management (view, edit, impersonate, notes)
- Service management (view all services, suspend, terminate, modify)
- Order management (pending orders, approvals)
- Invoice management (view, edit, manual invoicing)
- Coupon management (create, edit, deactivate)
- Plan management (create, edit, pricing changes)
- System configuration (email templates, tax rates, suspension policies)
- Audit log viewer
### Phase 6: Bandwidth Monitoring & Billing
- ElastiFlow API integration
- Bandwidth data collection and storage
- Usage calculation per billing cycle
- Bandwidth graphs in customer dashboard
- Multi-threshold alerts (75%, 90%, 100%)
- Automatic overage billing
- Admin bandwidth reports
### Phase 7: SupportPal Integration
- SSO implementation (Laravel Passport + SupportPal)
- Ticket viewing in customer dashboard
- Ticket creation via SupportPal API
- Webhook handlers for ticket updates
- Discord notifications for new tickets
### Phase 8: Marketing Frontend (ezscale.cloud)
- Product catalog pages (VPS, Dedicated, Hosting, Game Servers)
- Pricing pages with plan comparison
- Signup flow with plan selection
- Blog/news section
- Knowledge base / FAQ
- Legal pages (Terms, Privacy, AUP)
### Phase 9: Testing, Migration & Launch
- Comprehensive testing (unit, feature, integration, E2E)
- Security audit and penetration testing
- WHMCS data export and migration scripts
- Customer data migration (users, subscriptions, services, invoices)
- Parallel operation period (run both systems)
- Full cutover to new platform
- Monitoring and alerting setup
- Post-launch support and bug fixes
## 9. WHMCS Migration Plan
### Migration Scope (DECIDED)
- **Full historical data migration:**
- All customer accounts and profiles
- All subscriptions (active and cancelled)
- Complete invoice history
- Complete payment history
- All support tickets (migrate to SupportPal or archive)
- Service configurations
- Product/plan mapping
### Migration Approach
- **Customer Volume:** Medium (100-1000 customers)
- **Strategy:** Automated migration scripts with manual verification
- **Staging:** Test migration in staging environment first
- **Parallel Operation:** Run WHMCS and new platform in parallel for 30 days
- **Cutover:** Maintenance window for final cutover, redirect WHMCS URLs
### Migration Steps
1. Export WHMCS database to SQL dump
2. Map WHMCS product IDs to new plan IDs
3. Create migration scripts (Laravel commands):
- `php artisan migrate:whmcs-customers` - Import customers and profiles
- `php artisan migrate:whmcs-subscriptions` - Import active subscriptions (coordinate with Stripe/PayPal)
- `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
4. Verify data integrity in staging
5. Email customers about platform migration
6. Set up redirects from old WHMCS URLs
7. Execute final migration during maintenance window
8. Monitor for issues during parallel operation period
## 10. Open Questions & Decisions Needed
### Decided ✓
- [x] Payment gateway: Stripe + PayPal
- [x] Frontend stack: Vue 3 + Inertia.js
- [x] Infrastructure: VirtFusion, Pterodactyl, SynergyCP, Enhance
- [x] Bandwidth monitoring: ElastiFlow (NetFlow/sFlow)
- [x] Support system: SupportPal with full integration
- [x] Domain structure: ezscale.cloud / account / admin
- [x] Hosting: Own infrastructure with full DB redundancy
- [x] CI/CD: GitHub Actions with staging environment
- [x] Email: Mailgun or SendGrid
- [x] Admin security: Cloudflare Zero Trust + passkeys
- [x] Customer features: Full self-service (upgrades, downgrades, cancellations)
- [x] Provisioning: Fully automated for all service types
- [x] Analytics: Comprehensive dashboard (MRR, ARR, churn, etc.)
- [x] Multi-currency: Yes (Stripe supports this)
- [x] Coupons: Full system with all features
- [x] WHMCS migration: Full historical data import
### Still To Decide
- [ ] Tax calculation approach: TaxJar/Avalara integration vs manual tax rates?
- [ ] Email service final choice: Mailgun or SendGrid?
- [ ] Admin panel subdomain: admin.ezscale.cloud or something less obvious for security?
- [ ] Dedicated server semi-automation: How to handle limited hardware inventory (waitlist, manual approval)?
- [ ] NetFlow/sFlow deployment: Timeline for switching Juniper to flow exports?
- [x] ~~Customer portal theme/branding~~ **DECIDED: Vuexy VueJS + Laravel Admin Dashboard Template**
## 11. Tech Stack Summary
| Layer | Technology |
|-------|------------|
| **Framework** | Laravel 12 (PHP 8.2+) |
| **Frontend** | Vue 3 + Inertia.js + Tailwind CSS |
| **UI Theme** | Vuexy VueJS + Laravel Admin Dashboard |
| **Database** | MySQL 8.x (multi-region replication) |
| **Cache/Queue** | Redis |
| **Payments** | Laravel Cashier Stripe v16 + srmklive/laravel-paypal |
| **Auth** | Laravel Fortify + Passport (OAuth2) |
| **Roles** | spatie/laravel-permission |
| **Email** | Mailgun or SendGrid (via Laravel Mail) |
| **2FA** | TOTP (Authenticator apps) + WebAuthn (passkeys) |
| **Admin Security** | Cloudflare Zero Trust |
| **CI/CD** | GitHub Actions |
| **Monitoring** | ElastiFlow (bandwidth), Laravel Telescope (debugging) |
| **Provisioning APIs** | VirtFusion, Pterodactyl, SynergyCP, Enhance |
| **Support** | SupportPal (external integration) |
| **Notifications** | Laravel Notifications + Discord webhooks |

260
README.md Normal file
View File

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

340
TASKS.md Normal file
View File

@@ -0,0 +1,340 @@
# TASKS.md - EZSCALE Site Task Tracker
## Phase 1: Foundation & Core Setup
- [ ] Initialize Laravel 12 project with Vue + Inertia starter kit
- [ ] Configure domain routing (ezscale.cloud, account.ezscale.cloud, admin.ezscale.cloud)
- [ ] Set up MySQL 8.x with multi-region replication and automated backups
- [ ] Configure Redis (cache, queue, sessions)
- [ ] Install core dependencies:
- [ ] laravel/cashier (Stripe)
- [ ] laravel/fortify (authentication)
- [ ] laravel/passport (OAuth2 for SSO)
- [ ] srmklive/laravel-paypal
- [ ] spatie/laravel-permission
- [ ] Create complete database schema and migrations (users, profiles, plans, subscriptions, services, bandwidth, etc.)
- [ ] Set up Laravel Fortify with Vue/Inertia auth pages (login, register, verify)
- [ ] Implement 2FA (TOTP for customers, WebAuthn/passkeys for admins)
- [ ] Configure spatie roles: `admin` and `customer`
- [ ] Set up middleware: auth, role-based, rate limiting
- [ ] Configure Cloudflare Zero Trust for admin panel
- [ ] Set up GitHub Actions CI/CD pipeline
- [ ] Create staging environment (staging.account.ezscale.cloud)
- [ ] Configure Mailgun or SendGrid for emails
- [ ] Set up testing framework (PHPUnit/Pest)
## Phase 2: Billing & Subscriptions
- [ ] Implement `BillingServiceInterface` abstraction
- [ ] Build `StripeBillingService` (wraps Laravel Cashier)
- [ ] Build `PayPalBillingService` (wraps srmklive/laravel-paypal)
- [ ] Create plan catalog with all service types:
- [ ] VPS plans (various tiers with pricing)
- [ ] Dedicated server plans
- [ ] Web hosting plans
- [ ] Game server plans (Minecraft, ARK, etc.)
- [ ] Implement subscription creation flow (select plan → payment → provision)
- [ ] Build payment method management (multiple cards/PayPal per customer)
- [ ] Implement invoice generation (PDF, custom numbering, multi-currency)
- [ ] Set up webhook handlers for Stripe and PayPal
- [ ] Implement proration logic for upgrades/downgrades
- [ ] Build dunning system (failed payment handling, retry logic)
- [ ] Implement coupon system:
- [ ] Coupon creation and management (admin)
- [ ] Coupon redemption (customer checkout)
- [ ] Usage tracking and expiry
- [ ] Multi-currency support (EUR, GBP, USD, etc.)
- [ ] Tax calculation integration (TaxJar/Avalara or manual rates)
- [ ] Automatic suspension policy (X days past due → suspend → Y days → terminate)
## Phase 3: Provisioning Automation
- [ ] Create `ProvisioningServiceInterface` abstraction
- [ ] Build VirtFusion provisioning service:
- [ ] Create VPS via API
- [ ] Suspend/unsuspend VPS
- [ ] Terminate VPS
- [ ] Get status and resource usage
- [ ] Credential generation and secure storage
- [ ] Build Pterodactyl provisioning service:
- [ ] Create game server via API
- [ ] Suspend/unsuspend server
- [ ] Delete server
- [ ] Get server status and resources
- [ ] Build SynergyCP provisioning service:
- [ ] Provision dedicated server
- [ ] Suspend/unsuspend server
- [ ] Terminate server
- [ ] Get server details
- [ ] Handle limited hardware inventory (waitlist/semi-auto)
- [ ] Build Enhance provisioning service:
- [ ] Create web hosting account
- [ ] Suspend/delete account
- [ ] Get account status
- [ ] Implement event-driven provisioning (listen to `PaymentSucceeded` events)
- [ ] Build provisioning failure handling and retry logic
- [ ] Send credentials email on successful provisioning
- [ ] Log all provisioning actions to `provisioning_logs` table
## Phase 4: Customer Dashboard (account.ezscale.cloud)
- [ ] Build service overview dashboard:
- [ ] Active services list with status indicators
- [ ] Resource usage widgets (CPU, RAM, disk, bandwidth)
- [ ] Next invoice and payment due date
- [ ] Recent support tickets
- [ ] Quick actions (renew, upgrade, create ticket)
- [ ] Build service detail pages:
- [ ] VPS details (IP, credentials, resource graphs, control buttons)
- [ ] Game server details (connect info, resource usage, restart button)
- [ ] Dedicated server details (IPs, access info, bandwidth graph)
- [ ] Web hosting details (domain, cPanel/Enhance link, disk usage)
- [ ] Bandwidth usage graphs (from ElastiFlow integration)
- [ ] Billing section:
- [ ] Invoice history (with PDF download)
- [ ] Payment history
- [ ] Manage payment methods (add/remove cards, set default)
- [ ] Upcoming renewals
- [ ] Plan upgrade/downgrade flow (self-service with proration)
- [ ] Subscription cancellation flow (with optional survey)
- [ ] Profile and account settings:
- [ ] Contact information
- [ ] Billing/shipping addresses
- [ ] Tax ID
- [ ] Password change
- [ ] 2FA setup (TOTP, passkeys)
- [ ] SupportPal integration:
- [ ] SSO to SupportPal
- [ ] View recent tickets widget
- [ ] Create ticket button (opens SupportPal or API)
## Phase 5: Admin Panel (admin.ezscale.cloud)
- [ ] Analytics dashboard:
- [ ] MRR (Monthly Recurring Revenue) graph
- [ ] ARR (Annual Recurring Revenue)
- [ ] Churn rate calculation and graph
- [ ] Customer growth chart
- [ ] Revenue trends (daily, monthly, yearly)
- [ ] Popular plans and conversion rates
- [ ] Outstanding invoices total
- [ ] Overdue accounts list
- [ ] Customer management:
- [ ] Customer list (searchable, filterable)
- [ ] Customer detail view (profile, services, billing history, notes)
- [ ] Edit customer information
- [ ] Impersonate customer (with audit logging)
- [ ] Add admin notes to customer account
- [ ] View customer audit log
- [ ] Service management:
- [ ] All services list (filter by type, status, platform)
- [ ] Manually provision service
- [ ] Suspend/unsuspend service
- [ ] Terminate service
- [ ] Modify service (change plan, extend expiry)
- [ ] View provisioning logs
- [ ] Order management:
- [ ] Pending orders list
- [ ] Approve/reject orders (for semi-automated provisioning)
- [ ] View order details
- [ ] Invoice management:
- [ ] All invoices list (filter by status, date, customer)
- [ ] Create manual invoice
- [ ] Edit invoice (before sending)
- [ ] Void/refund invoice
- [ ] Resend invoice email
- [ ] Coupon management:
- [ ] Create coupon (percentage, fixed, applies to plans)
- [ ] Edit coupon details
- [ ] View redemption history
- [ ] Deactivate/delete coupon
- [ ] Plan management:
- [ ] Create new plan (set pricing, features, billing cycle)
- [ ] Edit existing plan
- [ ] Archive/hide plan
- [ ] Set stock quantity (for limited dedicated servers)
- [ ] System configuration:
- [ ] Email template editor
- [ ] Tax rate configuration (by region)
- [ ] Suspension policy settings (days before suspend/terminate)
- [ ] Bandwidth overage rates
- [ ] Discord webhook URLs
- [ ] API credentials (VirtFusion, Pterodactyl, etc.)
- [ ] Audit log viewer:
- [ ] Filter by user, action, date
- [ ] View changes (before/after state)
- [ ] Export logs
## Phase 6: Bandwidth Monitoring & Billing
- [ ] Set up NetFlow/sFlow export from Juniper switches
- [ ] Deploy ElastiFlow collector
- [ ] Build `BandwidthService` to query ElastiFlow API
- [ ] Create scheduled job to collect daily bandwidth data
- [ ] Store bandwidth usage in `bandwidth_usage` table
- [ ] Build bandwidth usage graphs for customer dashboard
- [ ] Implement multi-threshold alerts:
- [ ] 75% quota warning email
- [ ] 90% quota warning email
- [ ] 100% quota reached email
- [ ] Discord webhook for high usage customers
- [ ] Implement automatic overage billing:
- [ ] Calculate overages at end of billing cycle
- [ ] Generate overage invoice
- [ ] Email customer with overage details
- [ ] Build admin bandwidth reports:
- [ ] Top bandwidth users
- [ ] Total bandwidth by service type
- [ ] Overage revenue report
## Phase 7: SupportPal Integration
- [ ] Implement SSO for SupportPal:
- [ ] Laravel Passport OAuth2 integration
- [ ] SupportPal SAML or custom SSO config
- [ ] Test seamless login flow
- [ ] Build SupportPal API integration:
- [ ] Fetch user's recent tickets
- [ ] Create ticket via API
- [ ] Fetch ticket details and replies
- [ ] Build webhook handlers for SupportPal:
- [ ] New ticket created
- [ ] Ticket reply added
- [ ] Ticket status changed
- [ ] Ticket closed
- [ ] Display tickets in customer dashboard:
- [ ] Recent tickets widget
- [ ] Link to full ticket in SupportPal
- [ ] Admin ticket overview:
- [ ] Open tickets count
- [ ] Tickets by priority
- [ ] Link to SupportPal admin
- [ ] Discord notifications for tickets:
- [ ] New ticket opened
- [ ] Ticket escalated (high priority)
## Phase 8: Marketing Frontend (ezscale.cloud)
- [ ] Homepage:
- [ ] Hero section with value proposition
- [ ] Featured services/plans
- [ ] Trust indicators (uptime, customers, years in business)
- [ ] Call to action (Get Started, View Plans)
- [ ] Product pages:
- [ ] VPS hosting page with plan comparison
- [ ] Dedicated servers page with configurations
- [ ] Web hosting page with features
- [ ] Game server hosting page with supported games
- [ ] Pricing page:
- [ ] Interactive plan comparison table
- [ ] Currency selector (USD, EUR, GBP)
- [ ] Coupon code application
- [ ] Add to cart / checkout flow
- [ ] About page
- [ ] Contact page
- [ ] Blog/news section (optional, or use WordPress?)
- [ ] Knowledge base / FAQ:
- [ ] Getting started guides
- [ ] Tutorials
- [ ] Troubleshooting
- [ ] API documentation
- [ ] Legal pages:
- [ ] Terms of Service
- [ ] Privacy Policy
- [ ] Acceptable Use Policy
- [ ] SLA (Service Level Agreement)
- [ ] Signup flow:
- [ ] Plan selection
- [ ] Account creation
- [ ] Payment information
- [ ] Order confirmation
- [ ] Redirect to account dashboard
## Phase 9: API Development
- [ ] Customer API (RESTful, Sanctum auth):
- [ ] GET /api/v1/services - List customer's services
- [ ] GET /api/v1/services/{id} - Service details
- [ ] POST /api/v1/services/{id}/reboot - Reboot server
- [ ] GET /api/v1/invoices - Invoice history
- [ ] GET /api/v1/invoices/{id}/pdf - Download invoice PDF
- [ ] GET /api/v1/bandwidth - Bandwidth usage
- [ ] POST /api/v1/subscriptions/{id}/cancel - Cancel subscription
- [ ] POST /api/v1/tickets - Create support ticket
- [ ] Admin API:
- [ ] GET /api/v1/admin/customers - List all customers
- [ ] GET /api/v1/admin/services - List all services
- [ ] POST /api/v1/admin/services/{id}/suspend - Suspend service
- [ ] GET /api/v1/admin/analytics - Analytics data
- [ ] API documentation (OpenAPI/Swagger)
- [ ] API rate limiting and throttling
- [ ] API versioning strategy
## Phase 10: Testing, Migration & Launch
- [ ] Unit tests for all services and models
- [ ] Feature tests for critical user flows:
- [ ] Signup and subscription creation
- [ ] Payment processing (Stripe + PayPal)
- [ ] Service provisioning (all platforms)
- [ ] Upgrades/downgrades
- [ ] Cancellations
- [ ] Invoice generation
- [ ] Bandwidth overage billing
- [ ] Integration tests:
- [ ] VirtFusion API integration
- [ ] Pterodactyl API integration
- [ ] SynergyCP API integration
- [ ] Enhance API integration
- [ ] ElastiFlow API integration
- [ ] SupportPal API integration
- [ ] Security testing:
- [ ] Penetration testing (OWASP Top 10)
- [ ] Dependency vulnerability scanning
- [ ] CSRF and XSS testing
- [ ] SQL injection testing
- [ ] Rate limiting testing
- [ ] Performance testing:
- [ ] Load testing (100+ concurrent users)
- [ ] Database query optimization
- [ ] Redis caching implementation
- [ ] CDN for static assets
- [ ] WHMCS migration:
- [ ] Create migration commands:
- [ ] `migrate:whmcs-customers`
- [ ] `migrate:whmcs-subscriptions`
- [ ] `migrate:whmcs-invoices`
- [ ] `migrate:whmcs-payments`
- [ ] `migrate:whmcs-services`
- [ ] `migrate:whmcs-tickets`
- [ ] Test migration in staging
- [ ] Verify data integrity
- [ ] Map WHMCS product IDs to new plan IDs
- [ ] Coordinate Stripe/PayPal subscription transfer
- [ ] Pre-launch checklist:
- [ ] Email customers about migration
- [ ] Set up WHMCS URL redirects
- [ ] Configure monitoring (Laravel Telescope, log aggregation)
- [ ] Set up error tracking (Sentry, Bugsnag)
- [ ] Configure backups (database, files, Redis)
- [ ] DNS configuration for all domains
- [ ] SSL certificates for all domains
- [ ] Cloudflare Zero Trust for admin panel
- [ ] Launch:
- [ ] Execute final WHMCS migration during maintenance window
- [ ] Enable production mode
- [ ] Monitor for errors and performance issues
- [ ] 30-day parallel operation (keep WHMCS read-only)
- [ ] Gather customer feedback
- [ ] Address bugs and issues
- [ ] Post-launch:
- [ ] Monitor analytics and revenue
- [ ] Track customer satisfaction
- [ ] Iterate based on feedback
- [ ] Plan future features
## Phase 11: Future Enhancements (Post-Launch)
- [ ] Mobile app (iOS/Android) using API
- [ ] Advanced analytics (cohort analysis, LTV predictions)
- [ ] Automated resource scaling (auto-upgrade when limits reached)
- [ ] Custom server configurations (customer can configure RAM, CPU, disk)
- [ ] Marketplace for add-ons (additional IPs, backups, snapshots)
- [ ] Advanced bandwidth analytics (top talkers, traffic patterns)
- [ ] Integration with accounting software (QuickBooks, Xero)
- [ ] Advanced reporting (custom reports, scheduled exports)
- [ ] Customer referral program (instead of affiliates)
- [ ] Live chat support integration
- [ ] Status page for service health
- [ ] Automated security scanning for customer servers
- [ ] Backup management interface
- [ ] Server snapshots and restoration