website/CLAUDE.md

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

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