# 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