# CLAUDE.md - EZSCALE Site

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

## Phase Tracking (MANDATORY)
All work MUST be tracked against Gitea issues and `TASKS.md`. **Use Gitea MCP tools (`mcp__gitea__*`) — never `gh` CLI.**

1. **Before starting:** Check the relevant Gitea issue (`mcp__gitea__list_issues` for repo `EZSCALE/website`) and `TASKS.md` for current status.
2. **While working:** Update the Gitea issue with progress comments (`mcp__gitea__add_issue_comment`).
3. **After completing:** Update `TASKS.md` to check off completed items and close the corresponding Gitea issue.
4. **New tasks discovered:** Create sub-issues or add items to `TASKS.md` immediately.
5. **Commit messages:** Reference the Gitea issue number (e.g., `Fix checkout validation (#3)`).

Gitea repo: https://git.ezscale.cloud/EZSCALE/website
Gitea issues: https://git.ezscale.cloud/EZSCALE/website/issues

## Documentation Updates (MANDATORY)
When a phase or significant task is finished, update: `TASKS.md`, GitHub issues, `CLAUDE.md`, memory files, and `PROJECT_DEVELOPMENT.md` (if architecture changed).

### Visual Verification (MANDATORY)
After every successful `npm run build`:
1. Take headless Chrome screenshots of affected pages
2. Compare against the EZSCALE design system (navy blue palette, Plus Jakarta Sans, custom SCSS in `resources/styles/`)
3. Fix any visual discrepancies before considering the task complete
4. Key pages: Login/Register, Marketing homepage, Admin/Account dashboards, Pricing page

## Laravel App Location
The Laravel application is in **`website/`**. All artisan, composer, and npm commands run from there.

```
website/
├── app/
│   ├── Models/              # 29 Eloquent models
│   ├── Http/Controllers/    # Account/, Admin/, Api/V1/ controllers
│   ├── Http/Resources/      # API Resources
│   ├── Services/Billing/    # BillingServiceInterface, Stripe, PayPal, Dunning
│   ├── Events/              # Payment, Subscription events
│   ├── Listeners/           # Event handlers
│   └── Console/Commands/    # RetryProvisioning, SyncStripePrices
├── bootstrap/app.php        # Middleware, exceptions, routing (Laravel 12 slim — no Kernel files)
├── database/                # 59 migrations, 24 factories, seeders
├── resources/
│   ├── ts/                  # TypeScript source (Vue 3 + Inertia)
│   │   ├── types/           # Shared TypeScript interfaces
│   │   ├── Layouts/         # AccountLayout, AdminLayout, AuthLayout, MarketingLayout
│   │   ├── Components/      # Shared + marketing components
│   │   └── Pages/           # 85 Vue pages (Auth/7, Admin/41, Marketing/14, etc.)
│   └── styles/              # EZSCALE design system SCSS (8 files)
├── routes/                  # web, account, admin, marketing, webhooks, api
└── tests/                   # ~497 Pest tests
```

## Tech Stack
- **Framework:** Laravel 12 (PHP 8.3)
- **Frontend:** Vue 3 + Inertia.js v2 + TypeScript (REQUIRED) + Vuetify 3 + Vite 7
- **UI Theme:** Custom EZSCALE design system — navy blue `#1d4ed8`, Plus Jakarta Sans + JetBrains Mono (Bunny Fonts CDN), subdomain-aware theming (light for marketing, dark for admin/account)
- **Charts:** ECharts via `vue-echarts`
- **Utilities:** `@vueuse/core`
- **Testing:** Pest 4 + PHPUnit 12 (~497 tests)
- **Formatting:** Laravel Pint
- **Payments:** Laravel Cashier (Stripe) + srmklive/paypal (PayPal)
- **Database:** MySQL 8.x, database driver for sessions (Redis NOT installed)
- **Auth:** Laravel Fortify (login, register, 2FA, password reset, email verify) + Passport (OAuth2/SSO)
- **Roles:** spatie/laravel-permission (admin, customer)
- **Queue:** Laravel Horizon

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

## TypeScript Requirement (MANDATORY)
**All frontend code MUST use TypeScript.**

- All `.vue` files must use `<script setup lang="ts">` (never plain `<script setup>`)
- Props: `interface Props` + `withDefaults(defineProps<Props>(), {...})`
- Emits: `defineEmits<{ event: [payload: Type] }>()`
- Explicit types for `ref<Type>()`, `computed<Type>()`, and function return types
- No `any` type — use proper interfaces or type aliases
- Shared types go in `resources/ts/types/`
- Inertia page props should be typed with interfaces

## Design System

### Colors
- **Primary:** Navy blue `#1d4ed8`, lighter variant `#3b82f6`
- **Subdomain theming:** Marketing = light mode, Admin/Account = dark mode by default
- **Theme persistence:** localStorage key `ezscale-theme`, read on Vuetify init

### Typography
- **UI font:** Plus Jakarta Sans (Bunny Fonts CDN)
- **Code font:** JetBrains Mono (Bunny Fonts CDN)

### Key Patterns
- **Component ordering:** `<script lang="ts" setup>` then props interface, state, computed, methods, watchers
- **Layout system:** AppSidebar (collapsible) + AppTopNavbar (sticky) + CommandPalette (Cmd+K)
- **Navigation types:** `NavLink`, `NavGroup`, `NavSectionTitle` (see `resources/ts/@layouts/types.ts`)
- **State management:** Pinia stores (e.g., `stores/toast.ts`)
- **Icons:** Tabler icons via `@iconify/vue` (e.g., `tabler-smart-home`)

### Gotchas
- **User::billingInvoices()** — renamed from `invoices()` to avoid conflict with Laravel Cashier's built-in `invoices()` method. All call sites use `billingInvoices()`. The `withCount` uses alias `billing_invoices_count`.

## Agent Usage (MANDATORY)
Maximize use of subagents (Task tool) to reduce context usage. Main conversation should orchestrate; heavy lifting goes to agents.

- **Parallel agents**: Launch independent tasks as parallel agents, not sequentially in main context.
- **Delegate research**: Use `Explore` agents for codebase exploration and file searches.
- **Delegate implementation**: Use `general-purpose` agents for self-contained tasks.
- **Delegate reviews**: Use `feature-dev:code-reviewer` agents to review code after writing it.
- **Delegate architecture**: Use `feature-dev:code-architect` or `Plan` agents for feature design.
- **Background agents**: Use `run_in_background: true` for long-running tasks.
- **Batch similar work**: 10+ file updates with the same pattern go to an agent.
- **Frontend Design Skill**: ALWAYS run in background (`run_in_background: true`).

### Headless Chrome
```bash
google-chrome --headless=new --disable-gpu --no-sandbox --screenshot=/tmp/screenshot.png --window-size=1920,1080 --virtual-time-budget=15000 "URL"
```
- Must use `--headless=new`, `--virtual-time-budget=15000`, and `--no-sandbox`
- dbus errors in output are harmless — ignore them
- Read the resulting PNG with the Read tool to view it

## Code Conventions

### PHP
- PSR-12, enforced by Pint
- `declare(strict_types=1);` in all PHP files
- Explicit return types and parameter type hints
- PHP 8 constructor property promotion
- Form Request classes for validation (not inline in controllers)
- Service classes for business logic (thin controllers)
- Events/Listeners for side effects (email, provisioning)
- Eloquent over raw queries; avoid `DB::`, prefer `Model::query()`
- Eager loading to prevent N+1 queries
- `config()` only, never `env()` outside config files
- Named routes with `route()` helper
- Pest tests 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

### Frontend (Vue/TypeScript)
- Use Vuetify components directly (VCard, VBtn, VTextField, etc.) — not raw HTML
- Use Inertia `Link` component for navigation (not `<a>` tags)
- Use `useForm()` from `@inertiajs/vue3` for form submissions
- Status badges: VChip with `resolveStatusColor()` utilities
- Pinia stores for shared state
- ECharts via `vue-echarts` for charts

## Security
- All API endpoints require authentication
- Admin routes protected by role-based middleware
- CSRF on all forms (webhooks exempted via `bootstrap/app.php`)
- Rate limiting on auth and API endpoints
- Audit logging for admin actions and billing events

## Domains
- **ezscale.dev** (dev) / **ezscale.cloud** (prod) — marketing site
- **account.ezscale.dev** / **account.ezscale.cloud** — customer dashboard
- **admin.ezscale.dev** / **admin.ezscale.cloud** — admin panel (Cloudflare Zero Trust)
- Subdomain routing configured in `bootstrap/app.php` via `Route::domain()`

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

## Strategic Direction: WHMCS Replacement
This app is being built into a full WHMCS replacement for EZSCALE. Scope to track:

- **Storefront / catalog** — product browsing, configurable options, cart, checkout, multi-currency, quotes, coupons, tax (regional)
- **Billing** — subscriptions, invoices, dunning, credit balances, refunds, Stripe + PayPal (more gateways later)
- **Provisioning** — VirtFusion / SynergyCP / Enhance / Pterodactyl modules (idempotent, retry, suspension/termination hooks)
- **Customer area** — services list, KB, ticketing, login history, two-factor, affiliate dashboard, credits
- **Marketing site** — pricing, status page, blog, lead capture, affiliate landing pages
- **Admin panel** — RBAC staff, financial reports, fraud detection, dunning queue, manual invoice ops, refund flows
- **Notifications** — transactional email, Discord webhooks, Slack handoff to Ezra (see `infrastructure/`)
- **Marketing email automation** — drip campaigns, lifecycle/winback, broadcast announcements, segmented lists (lead/customer/lapsed), unsubscribe + preference center, deliverability hooks (Stalwart). *Active planning.*
- **Future** — domain registrar integration, SSL provisioning, reseller multi-tenancy (see `KASM_AND_MULTITENANCY.md`), API for partner integrations

When planning new work, check what's already shipped (recent commits cover KB, tickets v2, multi-currency, cart, quotes, affiliates, credits, staff RBAC, fraud detection, service panels, churn prevention, login history, financial reports, configurable checkout). Gap-analyze against WHMCS feature parity before building.

## Sister Projects (Reference)
The EZSCALE platform is split across three repositories, all on Gitea (`git.ezscale.cloud`). Read their `CLAUDE.md` files when touching cross-repo concerns; do not modify them from this repo.

**Catalog data model:** website/ owns the product catalog (SKUs, pricing, configurable options, descriptions). It *pulls* from various sources to populate inventory and capacity dynamically — most notably from `infrastructure/` for the VPS and dedicated server lineups. Treat infrastructure/ as the source-of-truth for hardware inventory, capacity, and rack reality; treat website/ as the source-of-truth for what's *for sale*, at what price, and to whom.

### `../infrastructure/` — Ops platform & Ezra AI agent
**Path:** `/home/andrew/local_projects/infrastructure/` · **Repo:** `git@git.ezscale.cloud:EZSCALE/infrastructure.git`

Houses everything that runs the *business* (not the storefront): K3s clusters (US/EU), Terraform-managed Cloudflare DNS, Ansible playbooks, the `web/` Laravel 13 admin panel that hosts **Ezra** (the AI ops agent — capacity scoring, MRR forecasting, ticket sync, customer intelligence, investor reports), plus deep reference docs.

**What website/ pulls from infrastructure/ (catalog inputs):**
- **VPS lineups** — VirtFusion package definitions, hypervisor capacity, plan availability per region. Source: `infrastructure/web/app/Services/ApiClients/VirtFusion*` + `Services/Capacity/`. Use to drive the `/vps` product pages and "stock available" indicators.
- **Dedicated server lineups** — SynergyCP inventory + the rack reality in `infrastructure/docs/reference/rack-atl.md` (server SKUs, specs, current allocations). Use to drive the `/dedicated` product pages.
- **Vendor costs / margins** — `infrastructure/docs/reference/business-costs.md` (Evocative, Hetzner, etc.). Reference when setting prices; never expose to customers.
- **IP availability** — `infrastructure/docs/reference/ip-resources.md` (ARIN vs Evocative leases). Drives whether IPv4 add-ons can be sold without a waitlist.

**Other intersections (non-catalog):**
- **API client patterns** — `infrastructure/web/app/Services/ApiClients/BaseApiClient` provides retry, rate-limit, and IPv4 DNS pinning. Port that base class here when our provisioning clients need the same hardening.
- **Customer intelligence** — `Services/Intelligence/` syncs scoring/segmentation. Website billing events should feed this; risk scores from it should drive fraud thresholds here.
- **Ticketing** — Ezra ingests SupportPal tickets and drafts AI responses. As website/ takes over ticketing, agree on a sync contract (or have Ezra read from our DB).
- **Reverse DNS / mail** — `Services/Rdns/` (PowerDNS) and Stalwart/SOGo. Customer rDNS requests in the account panel should flow through Ezra, not direct PowerDNS calls.
- **Identity** — Authentik IdP at `id.ezscale.cloud`. Staff SSO should integrate via SocialiteProviders/Authentik (already used in `infrastructure/web/`); customers stay on Fortify + Passport.
- **Other reference docs** — `powerdns.md`, `mail-server.md`, `authentik.md`, `llc-agreement.md`, `zfs-storage.md`, `uptime-kuma.md`, `hardware-monitoring.md`.

### `../ezscale_api/` — Battlelog/ACP SaaS API
**Path:** `/home/andrew/local_projects/ezscale_api/` · **Repo:** `git@git.ezscale.cloud:EZSCALE/api.git` · **Endpoint:** `api.ezscale.cloud`

Centralized Laravel 12 API at `api.ezscale.cloud` that fronts Battlelog (BF3/BF4/BFH) for the **ACP (Adkats Control Panel)** product — game-server admin SaaS sold to Battlefield community server operators. TimescaleDB-backed, single shared API key, multi-tenant ACP instances consume it.

**Key intersections with website/:**
- **As a product** — ACP is one SKU in the website catalog. When provisioning ACP, website calls into the ACP tenant orchestrator (separate from this API) but tenants in turn need the API key issued/revoked here.
- **API key lifecycle** — Currently a single static `EZSCALE_API_KEY`. When website starts selling ACP plans with usage limits, we'll likely need per-tenant keys here — coordinate before changing the auth model.
- **Real-time pattern** — Standalone Node.js Socket.IO + Redis pub/sub setup (`ezscale_api/socketio/`) is a reusable template if website needs live admin dashboards beyond polling.
- **Helm/K8s deployment template** — `ezscale_api/helm/ezscale-api/` is the cleanest deploy reference for our eventual K8s migration of website/.

### Cross-repo conventions
- **Git host:** Gitea at `git.ezscale.cloud` (NOT GitHub). Use `mcp__gitea__*` tools, never `gh` CLI for these repos.
- **DB hosts:** Each app has its own DB. Cross-repo data access is via HTTP APIs, never shared DB connections.
- **Docs format:** Each repo's `CLAUDE.md` is the canonical onboarding doc. `docs/superpowers/specs/` holds design docs; `docs/reference/` (in infrastructure) holds long-lived ops reference.

## Reference Docs
- `TASKS.md` — Task list and progress tracking
- `PROJECT_DEVELOPMENT.md` — Architecture decisions, database schema, API integrations
- `FEATURES.md` — Feature specifications
- `ADVANCED_FEATURES.md` — Advanced feature specs
- `KASM_AND_MULTITENANCY.md` — Kasm Workspaces + reseller multi-tenancy
- `GETTING_STARTED.md` — Development setup guide
- `docs/` — Deployment configs (`deployment/`), API specs (`integrations/`), scripts (`scripts/`), feature plans (`superpowers/`)
- `website/CLAUDE.md` — Laravel Boost guidelines (auto-generated)