# CLAUDE.md - EZSCALE Site

## Project
EZSCALE Site — Laravel 12 application replacing WHMCS for VPS/Dedicated Server hosting management (billing, subscriptions, provisioning, customer management, SSO).

## Laravel App Location
The Laravel application is in **`website/`**. All artisan, composer, and npm commands run from there. This is currently a **base Laravel 12 install** — no additional packages or custom code added yet.

```
website/               # Laravel 12 base install
├── app/               # Models, Http (Controllers), Providers
├── bootstrap/app.php  # Middleware, exceptions, routing (Laravel 12 style)
├── config/            # Standard Laravel config files
├── database/migrations/  # Default user, cache, jobs migrations only
├── resources/         # Views, JS, CSS
├── routes/            # web.php, console.php
├── tests/             # Pest 4 test suite
├── composer.json      # PHP 8.2+, Laravel 12, Pest 4, Pint
├── package.json       # Vite 7, Tailwind CSS 4, Axios
└── vite.config.js
```

## Tech Stack
- **Framework:** Laravel 12 (PHP 8.2+), Laravel 12 slim structure (no Kernel files)
- **Frontend:** Tailwind CSS 4 + Vite 7 (Vue 3 + Inertia.js to be added)
- **UI Theme:** Vuexy VueJS + Laravel Admin Dashboard Template (to be integrated)
- **Testing:** Pest 4 + PHPUnit 12
- **Formatting:** Laravel Pint
- **Payments:** Laravel Cashier Stripe + srmklive/laravel-paypal (to be installed)
- **Database:** MySQL 8.x, Redis for cache/queue/sessions
- **Auth:** Laravel Fortify + Passport (to be installed)
- **Roles:** spatie/laravel-permission (to be installed)

## Commands
```bash
cd website
composer run dev               # Start all dev servers (artisan serve + queue + pail + vite)
php artisan serve              # Laravel dev server only
php artisan test --compact     # Run Pest tests
php artisan migrate            # Run migrations
npm run dev                    # Vite dev server only
npm run build                  # Production build
vendor/bin/pint --dirty        # Format changed files
```

## Code Conventions
- PSR-12 coding standards, enforced by Pint
- `declare(strict_types=1);` in all PHP files
- Explicit return types and parameter type hints on all methods
- PHP 8 constructor property promotion
- Form Request classes for validation (not inline in controllers)
- Service classes for business logic (controllers stay thin)
- Policies for authorization
- Events/Listeners for side effects (email, provisioning, etc.)
- Eloquent models and relationships over raw DB queries; avoid `DB::`, prefer `Model::query()`
- Eager loading to prevent N+1 queries
- `config()` helper only, never `env()` outside config files
- Named routes with `route()` helper for URL generation
- Feature and Unit tests (Pest) for all new functionality
- Database transactions for multi-step operations
- Check sibling files for conventions before creating new files
- Run `vendor/bin/pint --dirty --format agent` before finalizing changes

## Security
- All API endpoints require authentication
- Admin routes protected by role-based middleware
- CSRF protection on all forms
- Rate limiting on auth and API endpoints
- Encrypted storage for sensitive data (API keys, credentials)
- Audit logging for admin actions and billing events

## Domains
- **ezscale.cloud** — Marketing site
- **account.ezscale.cloud** — Customer dashboard
- **admin.ezscale.cloud** — Admin panel (Cloudflare Zero Trust)
- **status.ezscale.cloud** — Public status page

## Key Business Domains
1. **Billing** — Subscriptions, invoices, payments (Stripe + PayPal)
2. **Provisioning** — VirtFusion (VPS), Pterodactyl (Game), SynergyCP (Dedicated), Enhance (Hosting)
3. **Customer Management** — Profiles, support tickets, notifications
4. **Admin Panel** — Dashboard, analytics, user/service management
5. **SSO** — Single sign-on via Laravel Passport

## Reference Docs
- `TASKS.md` — Task list and progress tracking
- `PROJECT_DEVELOPMENT.md` — Architecture decisions, database schema, API integrations
- `FEATURES.md` — Feature specifications (35+ features)
- `ADVANCED_FEATURES.md` — Advanced feature specs (28 features)
- `KASM_AND_MULTITENANCY.md` — Kasm Workspaces + reseller multi-tenancy
- `GETTING_STARTED.md` — Development setup guide
- `IDEAS.md` — Future feature ideas
- `website/CLAUDE.md` — Laravel Boost guidelines (auto-generated, Laravel/Pest/Pint conventions)