# CLAUDE.md - EZSCALE Site

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

## Phase Tracking (MANDATORY)
All work MUST be tracked against GitHub issues and `TASKS.md`:

1. **Before starting any phase work:** Check the relevant GitHub issue (see `gh issue list`) and `TASKS.md` for current status.
2. **While working:** Update the GitHub issue with progress comments as significant milestones are completed (e.g., `gh issue comment <number> --body "Completed X"`).
3. **After completing work:** Update `TASKS.md` to check off completed items and close/update the corresponding GitHub issue.
4. **New tasks discovered during work:** Create sub-issues or add items to `TASKS.md` immediately.
5. **Commit messages:** Reference the GitHub issue number (e.g., `Fix checkout validation (#3)`).

GitHub issues: https://github.com/EZSCALE/accounting/issues

## Documentation Updates (MANDATORY)
When a phase is completed or a significant task within a phase is finished:

1. **Update `TASKS.md`** — Check off completed items, add new items discovered during work
2. **Update GitHub issues** — Add progress comments (`gh issue comment <number> --body "..."`) and close completed issues
3. **Update `CLAUDE.md`** — Reflect any new tech stack changes, directory structure changes, or convention updates
4. **Update memory files** — Record key patterns, gotchas, and environment details learned during the work
5. **Update `PROJECT_DEVELOPMENT.md`** — If architectural decisions changed or new integrations were added

### Visual Verification (MANDATORY)
After every successful `npm run build`:
1. Take headless Chrome screenshots of affected pages
2. Compare layout and design against the EZSCALE design system (navy blue palette, Plus Jakarta Sans font, custom SCSS in `resources/styles/`)
3. Fix any visual discrepancies before considering the task complete
4. Key pages to verify:
   - Login/Register (split-screen auth layout with gradient art)
   - Marketing homepage (transparent navbar, animated heroes, mega footer)
   - Admin/Account dashboards (sidebar + top navbar layout)
   - Pricing page (service type tabs, billing cycle toggle)

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

```
website/
├── app/
│   ├── Models/              # 16 Eloquent models (Service uses SoftDeletes, TaxRate, EmailTemplate)
│   ├── Http/Controllers/    # Account/, Admin/, and Api/V1/ controllers
│   │   └── Api/V1/          # RESTful API controllers (Customer + Admin/)
│   ├── Http/Resources/      # API Resources (Service, Invoice, Subscription, Ticket, Customer, etc.)
│   ├── Services/Billing/    # BillingServiceInterface, Stripe, PayPal, Dunning
│   ├── Events/              # PaymentSucceeded/Failed, SubscriptionCreated/Cancelled
│   ├── Listeners/           # HandlePaymentSucceeded/Failed
│   ├── Console/Commands/      # RetryProvisioningCommand, SyncStripePrices
│   └── Providers/           # AppServiceProvider, FortifyServiceProvider
├── bootstrap/app.php        # Middleware, exceptions, routing (Laravel 12 style)
├── config/                  # App, auth, fortify, passport, cashier, paypal, permission
├── database/
│   ├── migrations/          # 44 migrations
│   ├── factories/           # 8 factories
│   └── seeders/             # Roles, plans, admin user
├── resources/
│   ├── ts/                    # TypeScript source (migrated from js/)
│   │   ├── app.ts             # Entry point with Vuetify + Pinia
│   │   ├── bootstrap.ts
│   │   ├── types/             # TypeScript interfaces
│   │   ├── utils/             # Resolvers, formatters
│   │   ├── stores/            # Pinia stores (toast.ts)
│   │   ├── navigation/        # account.ts, admin.ts, marketing.ts
│   │   ├── plugins/vuetify/   # theme.ts, defaults.ts, icons.ts, index.ts
│   │   ├── @layouts/          # Layout types (NavLink, NavGroup, NavSectionTitle)
│   │   ├── Layouts/           # AccountLayout, AdminLayout, AuthLayout, MarketingLayout
│   │   ├── Components/        # AppSidebar, AppTopNavbar, CommandPalette, ToastStack, NotificationPanel, SkeletonLoader, EmptyState, Breadcrumbs, StatCard, StatusChip, ThemeSwitcher, marketing/ (HeroSection, PricingCard, GlassCard, ScrollReveal, etc.)
│   │   └── Pages/             # Auth/ (7), Profile/ (2), Plans/ (1), Checkout/ (1), Subscriptions/ (2), Billing/ (3), Services/ (2), Tickets/ (3), Admin/ (30+), Marketing/ (12), Dashboard
│   ├── styles/                # Custom EZSCALE design system SCSS
│   │   ├── _variables.scss    # Design tokens (colors, spacing, typography)
│   │   ├── _mixins.scss       # Reusable SCSS mixins
│   │   ├── _animations.scss   # Keyframe animations and transitions
│   │   ├── _typography.scss   # Font definitions (Plus Jakarta Sans, JetBrains Mono)
│   │   ├── _component-overrides.scss  # Vuetify component style overrides
│   │   ├── _marketing.scss    # Marketing-specific styles
│   │   ├── _layouts.scss      # Layout-specific styles
│   │   ├── variables/         # _vuetify.scss, _template.scss
│   │   └── styles.scss        # Main entry — imports all design system files
│   ├── images/
│   └── views/app.blade.php    # Inertia root template
├── routes/                  # web.php, account.php, admin.php, marketing.php, webhooks.php, api.php
├── tests/                   # 252 Pest tests passing (1310 assertions)
├── composer.json
├── package.json
└── vite.config.js
```

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

## 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 agent  # Format changed files
```

## TypeScript Requirement (MANDATORY)
**All frontend code MUST use TypeScript.** This applies to all Vue components, composables, utilities, and type definitions.

### Rules
- All `.vue` files must use `<script setup lang="ts">` (never plain `<script setup>`)
- Define component props with `interface Props` and `withDefaults(defineProps<Props>(), {...})`
- Define emits with typed `defineEmits<{ event: [payload: Type] }>()`
- Use 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/` (e.g., `models.ts`, `billing.ts`)
- Inertia page props should be typed with interfaces

### Example Component Pattern
```vue
<script setup lang="ts">
import { Link } from '@inertiajs/vue3'
import AppLayout from '@/Layouts/AppLayout.vue'

interface Props {
  title: string
  items: Item[]
  count?: number
}

interface Item {
  id: number
  name: string
  status: 'active' | 'inactive'
}

defineOptions({ layout: AppLayout })

const props = withDefaults(defineProps<Props>(), {
  count: 0,
})

const isActive = computed<boolean>(() => props.count > 0)
</script>
```

## Design System

The EZSCALE design system replaces the previous Vuexy-based theme. Key design tokens and patterns:

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

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

### Key Patterns
- **Component structure:** `<script lang="ts" setup>` → props interface → state → computed → methods → watchers
- **Vuetify components:** VCard, VBtn, VTextField, VSelect, VTextarea, VIcon, VAvatar, VChip, VDataTable, etc.
- **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` for toast notifications)
- **Icons:** Tabler icons via `@iconify/vue` (e.g., `tabler-smart-home`, `tabler-chart-bar`)
- **Shared components:** AppSidebar, AppTopNavbar, CommandPalette, ToastStack, NotificationPanel, SkeletonLoader, EmptyState, Breadcrumbs
- **Marketing components:** HeroSection, NetworkHero, VpsHero, DedicatedHero, WebHostingHero, GameServerHero, GlassCard, ScrollReveal, PricingCard

### Model Notes
- **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)
Always maximize use of subagents (Task tool) to reduce context usage in the main conversation. This keeps the main terminal fast and avoids running out of context on large tasks.

### Rules
- **Parallel agents**: When multiple independent tasks exist (e.g., reading several files, researching different topics, building separate components), launch them as parallel agents in a single message rather than doing them sequentially in the main context.
- **Delegate research**: Use `Explore` agents for codebase exploration, file searches, and understanding existing patterns. Do not manually grep/read dozens of files in the main context.
- **Delegate implementation**: Use `general-purpose` agents for self-contained implementation tasks (e.g., "create this component", "write this migration", "update these 5 files with this pattern").
- **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 designing features before implementing.
- **Keep main context for orchestration**: The main conversation should coordinate agents, communicate with the user, and handle simple/quick edits. Heavy lifting goes to agents.
- **Background agents**: Use `run_in_background: true` for long-running tasks that don't block other work. Check results later with the Read tool on the output file.
- **Batch similar work**: If updating 10+ files with the same pattern, send them to an agent rather than editing each one in the main context.

### Frontend Design Skill
When using the `frontend-design` skill, **ALWAYS** run it in the background using `run_in_background: true`. Never run it in the main context window — it consumes significant context and produces large outputs. Check its output file when complete using the Read tool.

### Headless Chrome
Chrome is available for visual testing and screenshot comparison. Use it to verify UI matches design references.
```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`** (not just `--headless`) for modern headless mode
- **Must use `--virtual-time-budget=15000`** (or higher) to wait for SPA JavaScript to render before capturing
- **Must use `--no-sandbox`** in this environment
- dbus errors in output are harmless — ignore them
- After every successful `npm run build`, screenshot key pages to verify visual consistency
- Use for verifying layout, spacing, and component rendering
- Can be delegated to agents for parallel screenshot capture
- Read the resulting PNG with the Read tool to view it

### Examples of When to Use Agents
- Exploring how a feature works across multiple files → `Explore` agent
- Creating multiple Vue pages/components → parallel `general-purpose` agents
- Writing tests for new code → `general-purpose` agent
- Researching design system patterns → `Explore` agent
- Building a new API endpoint (controller + request + test) → `general-purpose` agent
- Reviewing changes before committing → `feature-dev:code-reviewer` agent

## Code Conventions

### PHP
- 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

### Frontend (Vue/TypeScript)
- All components use `<script setup lang="ts">`
- Props defined via `interface Props` + `defineProps<Props>()`
- Subdomain-aware theming: marketing = light, admin/account = dark (user can toggle, persisted to localStorage)
- Use Vuetify components directly (VCard, VBtn, VTextField, VSelect, VTextarea, VChip, etc.) — not raw HTML
- Use Inertia `Link` component for navigation (not `<a>` tags for internal links)
- Use `useForm()` from `@inertiajs/vue3` for form submissions
- Status badges use VChip with color prop and resolveStatusColor() utilities
- Use Pinia stores for shared state (e.g., `stores/toast.ts` for toast notifications)
- Use ECharts via `vue-echarts` for charts and analytics visualizations

## Security
- All API endpoints require authentication
- Admin routes protected by role-based middleware
- CSRF protection on all forms (webhooks exempted via `bootstrap/app.php`)
- 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.dev** → **ezscale.cloud** (marketing site) — dev uses `.dev`, production will use `.cloud`
- **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), Pterodactyl (Game), SynergyCP (Dedicated), Enhance (Hosting) — idempotent provisioning 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

## Reference Docs
- `TASKS.md` — Task list and progress tracking (update after each phase)
- `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)
- `SESSION_LOG_2026-03-14.md` — Full frontend redesign session log (design system, bug fixes)