EZSCALE/website
SHA256
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update README with current project status, optimize CLAUDE.md

Browse Source 
README: reflect completed phases (1-5, 8-9), accurate tech stack
(Vuetify 3 not Tailwind, Passport not Sanctum, standalone tickets
not SupportPal), current codebase counts (59 migrations, 29 models,
85 pages, ~497 tests), and separate implemented vs planned features.

CLAUDE.md: reduce from 281 to 184 lines — trim derivable directory
listings, remove stale counts, cut redundant examples, update all
metrics to current state.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Dev
2026-03-16 11:55:01 -04:00
parent 1d4a9f33f6
commit 2bf8a5b6bf
2 changed files with 268 additions and 375 deletions
Download Patch File Download Diff File Expand all files Collapse all files

249
CLAUDE.md
View File

@@ -1,38 +1,28 @@
# CLAUDE.md - EZSCALE Site # CLAUDE.md - EZSCALE Site
## Project ## Project
EZSCALE Site — Laravel 12 application replacing WHMCS for VPS/Dedicated Server hosting management (billing, subscriptions, provisioning, customer management, SSO). EZSCALE Site — Laravel 12 application for VPS/Dedicated Server hosting management (billing, subscriptions, provisioning, customer management, SSO).
## Phase Tracking (MANDATORY) ## Phase Tracking (MANDATORY)
All work MUST be tracked against GitHub issues and `TASKS.md`: 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. 1. **Before starting:** Check the relevant GitHub issue (`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"`). 2. **While working:** Update the GitHub issue with progress comments (`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. 3. **After completing:** Update `TASKS.md` to check off completed items and close the corresponding GitHub issue.
4. **New tasks discovered during work:** Create sub-issues or add items to `TASKS.md` immediately. 4. **New tasks discovered:** Create sub-issues or add items to `TASKS.md` immediately.
5. **Commit messages:** Reference the GitHub issue number (e.g., `Fix checkout validation (#3)`). 5. **Commit messages:** Reference the GitHub issue number (e.g., `Fix checkout validation (#3)`).
GitHub issues: https://github.com/EZSCALE/accounting/issues GitHub issues: https://github.com/EZSCALE/accounting/issues
## Documentation Updates (MANDATORY) ## Documentation Updates (MANDATORY)
When a phase is completed or a significant task within a phase is finished: When a phase or significant task is finished, update: `TASKS.md`, GitHub issues, `CLAUDE.md`, memory files, and `PROJECT_DEVELOPMENT.md` (if architecture changed).
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) ### Visual Verification (MANDATORY)
After every successful `npm run build`: After every successful `npm run build`:
1. Take headless Chrome screenshots of affected pages 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/`) 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 3. Fix any visual discrepancies before considering the task complete
4. Key pages to verify: 4. Key pages: Login/Register, Marketing homepage, Admin/Account dashboards, Pricing page
- 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 ## Laravel App Location
The Laravel application is in **`website/`**. All artisan, composer, and npm commands run from there. The Laravel application is in **`website/`**. All artisan, composer, and npm commands run from there.
@@ -40,241 +30,154 @@ The Laravel application is in **`website/`**. All artisan, composer, and npm com
``` ```
website/ website/
├── app/ ├── app/
│ ├── Models/ # 16 Eloquent models (Service uses SoftDeletes, TaxRate, EmailTemplate) │ ├── Models/ # 29 Eloquent models
│ ├── Http/Controllers/ # Account/, Admin/, and Api/V1/ controllers │ ├── Http/Controllers/ # Account/, Admin/, Api/V1/ controllers
│ │ └── Api/V1/ # RESTful API controllers (Customer + Admin/) │ ├── Http/Resources/ # API Resources
│ ├── Http/Resources/ # API Resources (Service, Invoice, Subscription, Ticket, Customer, etc.)
│ ├── Services/Billing/ # BillingServiceInterface, Stripe, PayPal, Dunning │ ├── Services/Billing/ # BillingServiceInterface, Stripe, PayPal, Dunning
│ ├── Events/ # PaymentSucceeded/Failed, SubscriptionCreated/Cancelled │ ├── Events/ # Payment, Subscription events
│ ├── Listeners/ # HandlePaymentSucceeded/Failed │ ├── Listeners/ # Event handlers
│ ├── Console/Commands/ # RetryProvisioningCommand, SyncStripePrices │ └── Console/Commands/ # RetryProvisioning, SyncStripePrices
│ └── Providers/ # AppServiceProvider, FortifyServiceProvider ├── bootstrap/app.php # Middleware, exceptions, routing (Laravel 12 slim — no Kernel files)
├── bootstrap/app.php # Middleware, exceptions, routing (Laravel 12 style) ├── database/ # 59 migrations, 24 factories, seeders
├── config/ # App, auth, fortify, passport, cashier, paypal, permission
├── database/
│ ├── migrations/ # 44 migrations
│ ├── factories/ # 8 factories
│ └── seeders/ # Roles, plans, admin user
├── resources/ ├── resources/
│ ├── ts/ # TypeScript source (migrated from js/) │ ├── ts/ # TypeScript source (Vue 3 + Inertia)
│ │ ├── app.ts # Entry point with Vuetify + Pinia │ │ ├── types/ # Shared TypeScript interfaces
│ │ ├── 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 │ │ ├── Layouts/ # AccountLayout, AdminLayout, AuthLayout, MarketingLayout
│ │ ├── Components/ # AppSidebar, AppTopNavbar, CommandPalette, ToastStack, NotificationPanel, SkeletonLoader, EmptyState, Breadcrumbs, StatCard, StatusChip, ThemeSwitcher, marketing/ (HeroSection, PricingCard, GlassCard, ScrollReveal, etc.) │ │ ├── Components/ # Shared + marketing components
│ │ └── Pages/ # Auth/ (7), Profile/ (2), Plans/ (1), Checkout/ (1), Subscriptions/ (2), Billing/ (3), Services/ (2), Tickets/ (3), Admin/ (30+), Marketing/ (12), Dashboard │ │ └── Pages/ # 85 Vue pages (Auth/7, Admin/41, Marketing/14, etc.)
│ ├── styles/ # Custom EZSCALE design system SCSS │ └── styles/ # EZSCALE design system SCSS (8 files)
│ │ ├── _variables.scss # Design tokens (colors, spacing, typography) ├── routes/ # web, account, admin, marketing, webhooks, api
│ │ ├── _mixins.scss # Reusable SCSS mixins └── tests/ # ~497 Pest tests
│ │ ├── _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 ## Tech Stack
- **Framework:** Laravel 12 (PHP 8.3), Laravel 12 slim structure (no Kernel files) - **Framework:** Laravel 12 (PHP 8.3)
- **Frontend:** Vue 3 + Inertia.js v2 + TypeScript (REQUIRED) + Vuetify 3 + Vite 7 - **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) - **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` for analytics dashboards - **Charts:** ECharts via `vue-echarts`
- **Utilities:** `@vueuse/core` for composable utilities - **Utilities:** `@vueuse/core`
- **Testing:** Pest 4 + PHPUnit 12 (347 tests, 1866 assertions) - **Testing:** Pest 4 + PHPUnit 12 (~497 tests)
- **Formatting:** Laravel Pint - **Formatting:** Laravel Pint
- **Payments:** Laravel Cashier (Stripe) + srmklive/paypal (PayPal) - **Payments:** Laravel Cashier (Stripe) + srmklive/paypal (PayPal)
- **Database:** MySQL 8.x, Redis for cache/queue/sessions - **Database:** MySQL 8.x, database driver for sessions (Redis NOT installed)
- **Auth:** Laravel Fortify (login, register, 2FA, password reset, email verify) + Passport (OAuth2/SSO) - **Auth:** Laravel Fortify (login, register, 2FA, password reset, email verify) + Passport (OAuth2/SSO)
- **Roles:** spatie/laravel-permission (admin, customer) - **Roles:** spatie/laravel-permission (admin, customer)
- **Queue:** Laravel Horizon for queue management - **Queue:** Laravel Horizon
## Commands ## Commands
```bash ```bash
cd website cd website
composer run dev # Start all dev servers (artisan serve + queue + pail + vite) 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 test --compact # Run Pest tests
php artisan migrate # Run migrations
npm run dev # Vite dev server only
npm run build # Production build npm run build # Production build
vendor/bin/pint --dirty --format agent # Format changed files vendor/bin/pint --dirty --format agent # Format changed files
``` ```
## TypeScript Requirement (MANDATORY) ## TypeScript Requirement (MANDATORY)
**All frontend code MUST use TypeScript.** This applies to all Vue components, composables, utilities, and type definitions. **All frontend code MUST use TypeScript.**
### Rules
- All `.vue` files must use `<script setup lang="ts">` (never plain `<script setup>`) - All `.vue` files must use `<script setup lang="ts">` (never plain `<script setup>`)
- Define component props with `interface Props` and `withDefaults(defineProps<Props>(), {...})` - Props: `interface Props` + `withDefaults(defineProps<Props>(), {...})`
- Define emits with typed `defineEmits<{ event: [payload: Type] }>()` - Emits: `defineEmits<{ event: [payload: Type] }>()`
- Use explicit types for `ref<Type>()`, `computed<Type>()`, and function return types - Explicit types for `ref<Type>()`, `computed<Type>()`, and function return types
- No `any` type — use proper interfaces or type aliases - No `any` type — use proper interfaces or type aliases
- Shared types go in `resources/ts/types/` (e.g., `models.ts`, `billing.ts`) - Shared types go in `resources/ts/types/`
- Inertia page props should be typed with interfaces - 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 ## Design System
The EZSCALE design system replaces the previous Vuexy-based theme. Key design tokens and patterns:
### Colors ### Colors
- **Primary:** Navy blue `#1d4ed8`, lighter variant `#3b82f6` - **Primary:** Navy blue `#1d4ed8`, lighter variant `#3b82f6`
- **Subdomain theming:** Marketing uses light mode, Admin/Account use dark mode by default - **Subdomain theming:** Marketing = light mode, Admin/Account = dark mode by default
- **Theme persistence:** User preference saved to localStorage key `ezscale-theme`, read on Vuetify init - **Theme persistence:** localStorage key `ezscale-theme`, read on Vuetify init
### Typography ### Typography
- **UI font:** Plus Jakarta Sans (via Bunny Fonts CDN) - **UI font:** Plus Jakarta Sans (Bunny Fonts CDN)
- **Code font:** JetBrains Mono (via Bunny Fonts CDN) - **Code font:** JetBrains Mono (Bunny Fonts CDN)
### Key Patterns ### Key Patterns
- **Component structure:** `<script lang="ts" setup>` → props interface → state → computed → methods → watchers - **Component ordering:** `<script lang="ts" setup>` then 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) - **Layout system:** AppSidebar (collapsible) + AppTopNavbar (sticky) + CommandPalette (Cmd+K)
- **Navigation types:** `NavLink`, `NavGroup`, `NavSectionTitle` (see `resources/ts/@layouts/types.ts`) - **Navigation types:** `NavLink`, `NavGroup`, `NavSectionTitle` (see `resources/ts/@layouts/types.ts`)
- **State management:** Pinia stores (e.g., `stores/toast.ts` for toast notifications) - **State management:** Pinia stores (e.g., `stores/toast.ts`)
- **Icons:** Tabler icons via `@iconify/vue` (e.g., `tabler-smart-home`, `tabler-chart-bar`) - **Icons:** Tabler icons via `@iconify/vue` (e.g., `tabler-smart-home`)
- **Shared components:** AppSidebar, AppTopNavbar, CommandPalette, ToastStack, NotificationPanel, SkeletonLoader, EmptyState, Breadcrumbs
- **Marketing components:** HeroSection, NetworkHero, VpsHero, DedicatedHero, WebHostingHero, GameServerHero, GlassCard, ScrollReveal, PricingCard
### Model Notes ### 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`. - **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) ## 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. Maximize use of subagents (Task tool) to reduce context usage. Main conversation should orchestrate; heavy lifting goes to agents.
### Rules - **Parallel agents**: Launch independent tasks as parallel agents, not sequentially in main context.
- **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 and file searches.
- **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 tasks.
- **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 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. - **Delegate architecture**: Use `feature-dev:code-architect` or `Plan` agents for feature design.
- **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.
- **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**: 10+ file updates with the same pattern go to an agent.
- **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**: ALWAYS run in background (`run_in_background: true`).
### 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 ### Headless Chrome
Chrome is available for visual testing and screenshot comparison. Use it to verify UI matches design references.
```bash ```bash
google-chrome --headless=new --disable-gpu --no-sandbox --screenshot=/tmp/screenshot.png --window-size=1920,1080 --virtual-time-budget=15000 "URL" 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 `--headless=new`, `--virtual-time-budget=15000`, and `--no-sandbox`
- **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 - 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 - 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 ## Code Conventions
### PHP ### PHP
- PSR-12 coding standards, enforced by Pint - PSR-12, enforced by Pint
- `declare(strict_types=1);` in all PHP files - `declare(strict_types=1);` in all PHP files
- Explicit return types and parameter type hints on all methods - Explicit return types and parameter type hints
- PHP 8 constructor property promotion - PHP 8 constructor property promotion
- Form Request classes for validation (not inline in controllers) - Form Request classes for validation (not inline in controllers)
- Service classes for business logic (controllers stay thin) - Service classes for business logic (thin controllers)
- Policies for authorization - Events/Listeners for side effects (email, provisioning)
- Events/Listeners for side effects (email, provisioning, etc.) - Eloquent over raw queries; avoid `DB::`, prefer `Model::query()`
- Eloquent models and relationships over raw DB queries; avoid `DB::`, prefer `Model::query()`
- Eager loading to prevent N+1 queries - Eager loading to prevent N+1 queries
- `config()` helper only, never `env()` outside config files - `config()` only, never `env()` outside config files
- Named routes with `route()` helper for URL generation - Named routes with `route()` helper
- Feature and Unit tests (Pest) for all new functionality - Pest tests for all new functionality
- Database transactions for multi-step operations - Database transactions for multi-step operations
- Check sibling files for conventions before creating new files - Check sibling files for conventions before creating new files
- Run `vendor/bin/pint --dirty --format agent` before finalizing changes - Run `vendor/bin/pint --dirty --format agent` before finalizing
### Frontend (Vue/TypeScript) ### Frontend (Vue/TypeScript)
- All components use `<script setup lang="ts">` - Use Vuetify components directly (VCard, VBtn, VTextField, etc.) — not raw HTML
- Props defined via `interface Props` + `defineProps<Props>()` - Use Inertia `Link` component for navigation (not `<a>` tags)
- 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 - Use `useForm()` from `@inertiajs/vue3` for form submissions
- Status badges use VChip with color prop and resolveStatusColor() utilities - Status badges: VChip with `resolveStatusColor()` utilities
- Use Pinia stores for shared state (e.g., `stores/toast.ts` for toast notifications) - Pinia stores for shared state
- Use ECharts via `vue-echarts` for charts and analytics visualizations - ECharts via `vue-echarts` for charts
## Security ## Security
- All API endpoints require authentication - All API endpoints require authentication
- Admin routes protected by role-based middleware - Admin routes protected by role-based middleware
- CSRF protection on all forms (webhooks exempted via `bootstrap/app.php`) - CSRF on all forms (webhooks exempted via `bootstrap/app.php`)
- Rate limiting on auth and API endpoints - Rate limiting on auth and API endpoints
- Encrypted storage for sensitive data (API keys, credentials)
- Audit logging for admin actions and billing events - Audit logging for admin actions and billing events
## Domains ## Domains
- **ezscale.dev** → **ezscale.cloud** (marketing site) — dev uses `.dev`, production will use `.cloud` - **ezscale.dev** (dev) / **ezscale.cloud** (prod) — marketing site
- **account.ezscale.dev** → **account.ezscale.cloud** (customer dashboard) - **account.ezscale.dev** / **account.ezscale.cloud** — customer dashboard
- **admin.ezscale.dev** → **admin.ezscale.cloud** (admin panel, Cloudflare Zero Trust) - **admin.ezscale.dev** / **admin.ezscale.cloud** — admin panel (Cloudflare Zero Trust)
- Subdomain routing configured in `bootstrap/app.php` via `Route::domain()` - Subdomain routing configured in `bootstrap/app.php` via `Route::domain()`
## Key Business Domains ## Key Business Domains
1. **Billing** — Subscriptions, invoices, payments (Stripe + PayPal), dunning, coupons 1. **Billing** — Subscriptions, invoices, payments (Stripe + PayPal), dunning, coupons
2. **Provisioning** — VirtFusion (VPS), Pterodactyl (Game), SynergyCP (Dedicated), Enhance (Hosting) — idempotent provisioning with retry 2. **Provisioning** — VirtFusion (VPS), SynergyCP (Dedicated), Enhance (Hosting), Pterodactyl (Game) — idempotent with retry
3. **Customer Management** — Profiles, support tickets, notifications 3. **Customer Management** — Profiles, support tickets, notifications
4. **Admin Panel** — Dashboard, analytics, user/service management 4. **Admin Panel** — Dashboard, analytics, user/service management
5. **SSO** — Single sign-on via Laravel Passport 5. **SSO** — Single sign-on via Laravel Passport
## Reference Docs ## Reference Docs
- `TASKS.md` — Task list and progress tracking (update after each phase) - `TASKS.md` — Task list and progress tracking
- `PROJECT_DEVELOPMENT.md` — Architecture decisions, database schema, API integrations - `PROJECT_DEVELOPMENT.md` — Architecture decisions, database schema, API integrations
- `FEATURES.md` — Feature specifications (35+ features) - `FEATURES.md` — Feature specifications
- `ADVANCED_FEATURES.md` — Advanced feature specs (28 features) - `ADVANCED_FEATURES.md` — Advanced feature specs
- `KASM_AND_MULTITENANCY.md` — Kasm Workspaces + reseller multi-tenancy - `KASM_AND_MULTITENANCY.md` — Kasm Workspaces + reseller multi-tenancy
- `GETTING_STARTED.md` — Development setup guide - `GETTING_STARTED.md` — Development setup guide
- `IDEAS.md` — Future feature ideas - `docs/` — Deployment configs (`deployment/`), API specs (`integrations/`), scripts (`scripts/`), feature plans (`superpowers/`)
- `website/CLAUDE.md` — Laravel Boost guidelines (auto-generated, Laravel/Pest/Pint conventions) - `website/CLAUDE.md` — Laravel Boost guidelines (auto-generated)

392
README.md
View File

@@ -1,268 +1,258 @@
# EZSCALE Billing Platform # EZSCALE Billing Platform
Modern Laravel 12 billing and customer management platform replacing WHMCS for EZSCALE Hosting. Modern Laravel 12 billing and customer management platform replacing WHMCS for EZSCALE Hosting. Handles subscription billing, automated service provisioning, customer support, and admin analytics across VPS, Dedicated Server, Web Hosting, and Game Server products.
## Repository ## Repository
- **GitHub**: git@github.com:EZSCALE/accounting.git - **GitHub**: git@github.com:EZSCALE/accounting.git
- **Branch Strategy**: Feature branches → `develop` → `main` - **Branch**: `main` (direct commits)
## Documentation Files ## Documentation Files
| File | Purpose | Lines | | File | Purpose | Lines |
|------|---------|-------| |------|---------|-------|
| **CLAUDE.md** | Project instructions for AI assistance | ~80 | | **CLAUDE.md** | Project instructions for AI assistance | ~280 |
| **PROJECT_DEVELOPMENT.md** | Complete architecture & development plan | ~600 | | **PROJECT_DEVELOPMENT.md** | Complete architecture & development plan | ~600 |
| **TASKS.md** | Detailed task breakdown (13 phases) | ~400 | | **TASKS.md** | Detailed task breakdown (13 phases) | ~390 |
| **FEATURES.md** | Feature specifications (35+ features) | ~1000 | | **FEATURES.md** | Feature specifications (35+ features) | ~1330 |
| **KASM_AND_MULTITENANCY.md** | Kasm Workspaces + Multi-Tenancy implementation | ~600 | | **KASM_AND_MULTITENANCY.md** | Kasm Workspaces + Multi-Tenancy specs | ~930 |
| **GETTING_STARTED.md** | Development setup guide | ~300 | | **GETTING_STARTED.md** | Development setup guide | ~400 |
| **ADVANCED_FEATURES.md** | Advanced feature specifications (28 features) | ~1400 | | **ADVANCED_FEATURES.md** | Advanced feature specifications (28 features) | ~1440 |
| **IDEAS.md** | Future feature ideas and exploration topics | ~500 | | **IDEAS.md** | Future feature ideas and exploration topics | ~530 |
| **README.md** | This file - project overview | - | | **docs/** | Deployment configs, integration specs, scripts | - |
| **website/** | Laravel 12 base installation | - | | **scripts/whmcs-migrate/** | WHMCS data migration scripts | - |
| **website/** | Laravel 12 application | - |
## Quick Overview ## Tech Stack
### What We're Building - **Framework**: Laravel 12 (PHP 8.3)
A comprehensive billing and service management platform for EZSCALE Hosting that handles: - **Frontend**: Vue 3 + Inertia.js v2 + TypeScript + Vuetify 3 + Vite 7
- **Services**: VPS, Dedicated Servers, Web Hosting, Game Servers, **Kasm Workspaces** - **Design System**: Custom EZSCALE theme — navy blue primary (`#1d4ed8`), Plus Jakarta Sans + JetBrains Mono (Bunny Fonts CDN)
- **Billing**: Stripe + PayPal + Crypto with multi-currency support - **Charts**: ECharts via `vue-echarts`
- **Provisioning**: Fully automated via VirtFusion, Pterodactyl, SynergyCP, Enhance APIs - **Utilities**: `@vueuse/core` composables, Pinia state management
- **Monitoring**: ElastiFlow bandwidth tracking, uptime monitoring, status page - **Database**: MySQL 8.x
- **Support**: Deep SupportPal integration with SSO - **Sessions**: Database driver
- **Admin**: Comprehensive analytics, MRR/ARR/churn tracking, full customer control - **Queue**: Laravel Horizon
- **Payments**: Laravel Cashier (Stripe) + srmklive/paypal (PayPal)
- **Auth**: Laravel Fortify (login, register, 2FA, password reset, email verify) + Passport (OAuth2/SSO for API)
- **Roles**: spatie/laravel-permission (`admin`, `customer`)
- **Testing**: Pest 4 + PHPUnit 12
- **Formatting**: Laravel Pint
- **PDF**: barryvdh/laravel-dompdf (invoices, financial reports)
### Tech Stack ## Domains
- **Framework**: Laravel 12 (PHP 8.2+)
- **Frontend**: Vue 3 + Inertia.js + Tailwind CSS
- **UI Theme**: Vuexy VueJS + Laravel Admin Dashboard Template
- **Database**: MySQL 8.x (multi-region replication, 15-min backups)
- **Cache/Queue**: Redis + Laravel Horizon
- **Payments**: Laravel Cashier Stripe v16 + srmklive/laravel-paypal
- **Auth**: Laravel Fortify + Passport (OAuth2/SSO)
- **Email**: Mailgun or SendGrid
- **Monitoring**: ElastiFlow (NetFlow/sFlow), built-in uptime checks
- **CI/CD**: GitHub Actions with staging environment
- **Security**: Cloudflare Zero Trust + 2FA/passkeys
### Domains | Domain (Dev) | Domain (Production) | Purpose |
- **ezscale.cloud** — Marketing site, product catalog, public pages |---|---|---|
- **account.ezscale.cloud** — Customer dashboard, service management | ezscale.dev | ezscale.cloud | Marketing site |
- **admin.ezscale.cloud** — Admin panel (Cloudflare Zero Trust protected) | account.ezscale.dev | account.ezscale.cloud | Customer dashboard |
- **status.ezscale.cloud** — Public status page | admin.ezscale.dev | admin.ezscale.cloud | Admin panel (Cloudflare Zero Trust) |
### Key Features ## Current Status
- ✅ Fully automated provisioning (VPS, Dedicated, Hosting, Game Servers)
- ✅ Multi-currency billing (USD, EUR, GBP, etc.)
- ✅ Advanced coupon system (stackable, geo-restricted, A/B testing)
- ✅ Automatic loyalty rewards (5-20% based on tenure)
- ✅ Self-service upgrades/downgrades with proration
- ✅ Bandwidth monitoring with auto-billing overages
- ✅ Team accounts with granular permissions
- ✅ Referral credit system
- ✅ Free trial support
- ✅ Comprehensive API with webhooks
- ✅ Built-in abuse management system
- ✅ Fraud detection and prevention
- ✅ Customer custom domains (CNAME support)
- ✅ Cryptocurrency payment support
- ✅ Exit surveys and win-back campaigns
- ✅ Real-time dashboard (WebSockets + polling)
- ✅ Multi-channel admin alerts (Discord, Email, SMS)
- ✅ GDPR-compliant data deletion
- ✅ Full audit trail and login history
- ✅ Unified communication timeline
## Current Status: Base Install Complete ### Implemented Features
The **Laravel 12 base installation** exists in the `website/` directory. Planning and documentation is complete. No additional packages or customizations have been added yet. - Fully automated provisioning (VPS, Dedicated, Hosting, Game Servers)
- Stripe + PayPal subscription billing with dunning
- Self-service plan upgrades/downgrades with proration
- Coupon system (percentage and fixed discounts)
- Invoice PDF generation and email delivery
- Comprehensive admin panel with MRR/ARR/churn analytics
- Customer management with impersonation, notes, and audit logs
- Service management with soft-delete archive/restore
- Standalone support ticket system with IMAP email integration
- 2FA (TOTP) with trusted device management
- Login history with new-device detection and notifications
- Cancellation surveys and automated win-back campaigns
- Financial reports (Revenue, P&L, Tax, Aging, Refund, Subscription) with PDF/CSV/JSON export
- REST API with Passport auth (customer + admin endpoints, rate-limited)
- 12 marketing pages + 4 legal pages with custom design system
- Notification system (mail + database channels) for payment, subscription, provisioning events
- Command palette (Cmd+K) and dark/light theme toggle
- Demo data seeder (300 customers, 500 subscriptions, 800 invoices)
### Planning Complete ✓ ### Not Yet Implemented
- [x] Infrastructure architecture designed
- [x] Database schema defined
- [x] All integrations documented (6 external APIs)
- [x] Feature specifications written (35+ features)
- [x] Development phases outlined (11 phases)
- [x] Task breakdown completed (200+ tasks)
- [x] Security architecture defined
- [x] WHMCS migration strategy planned
- [x] Laravel 12 base install created (`website/`)
### Next Steps - Multi-currency support
1. Install core dependencies (Cashier, Fortify, Passport, PayPal, Spatie) - Bandwidth monitoring (ElastiFlow integration) and overage billing
2. Configure environment and database - Blog and knowledge base / FAQ
3. Create database schema and migrations - WHMCS data migration (scripts in `scripts/whmcs-migrate/`, artisan commands not yet built)
4. Begin Phase 1: Foundation (auth, database, core setup) - CI/CD pipeline (GitHub Actions)
- Staging environment
- Cloudflare Zero Trust configuration for admin panel
## Development Phases ## Development Phases
| Phase | Focus | Status | | Phase | Focus | Status |
|-------|-------|--------| |-------|-------|--------|
| **Phase 1** | Foundation & Core Setup | Planned | | **Phase 1** | Foundation & Core Setup | Complete |
| **Phase 2** | Billing & Subscriptions | Planned | | **Phase 2** | Billing & Subscriptions | Complete (multi-currency planned) |
| **Phase 3** | Provisioning Automation | Planned | | **Frontend** | Redesign (Vuexy to custom EZSCALE design system) | Complete |
| **Phase 4** | Customer Dashboard | Planned | | **Phase 3** | Provisioning Automation | Complete |
| **Phase 5** | Admin Panel | Planned | | **Phase 4** | Customer Dashboard | Mostly Complete (bandwidth graphs depend on Phase 6) |
| **Phase 6** | Bandwidth Monitoring & Billing | Planned | | **Phase 5** | Admin Panel | Complete |
| **Phase 7** | SupportPal Integration | Planned | | **Phase 6** | Bandwidth Monitoring & Billing | Not Started |
| **Phase 8** | Marketing Frontend | Planned | | **Phase 7** | SupportPal Integration | Replaced by standalone ticket system |
| **Phase 9** | RESTful API | Planned | | **Phase 8** | Marketing Frontend | Mostly Complete (blog, KB/FAQ planned) |
| **Phase 10** | Testing, Migration & Launch | Planned | | **Phase 9** | REST API | Complete |
| **Phase 10** | Testing, Migration & Launch | In Progress |
| **Phase 11** | Future Enhancements | Backlog | | **Phase 11** | Future Enhancements | Backlog |
| **Phase 12** | Kasm Workspaces Integration | Planned | | **Phase 12** | Kasm Workspaces Integration | Planned |
| **Phase 13** | Multi-Tenancy (Resellers) | Planned | | **Phase 13** | Multi-Tenancy (Resellers) | Planned |
## Infrastructure Integration ### Additional Completed Work (outside phase numbering)
### Service Provisioning - Login history and trusted device management
| Platform | Service Type | API | Automation | - Churn prevention (cancellation surveys + win-back campaigns)
|----------|-------------|-----|------------| - Financial reporting suite (6 report types with export)
| **VirtFusion** | VPS | REST API | Fully automated | - Notification system (8 notification types, mail + database)
| **Pterodactyl** | Game Servers | REST API | Fully automated |
| **SynergyCP** | Dedicated Servers | REST API | Automated (semi-auto for inventory) |
| **Enhance** | Web Hosting | REST API | Fully automated |
### Support & Monitoring ## Codebase at a Glance
| System | Purpose | Integration |
|--------|---------|-------------| | Category | Count |
| **SupportPal** | Ticketing | SSO + Full API integration | |----------|-------|
| **ElastiFlow** | Bandwidth Monitoring | API queries for usage data | | Database migrations | 59 |
| **Juniper Switches** | Network | NetFlow/sFlow exports | | Eloquent models | 29 |
| Model factories | 24 |
| Vue pages | 85 |
| Vue components | 26 |
| Test files | 43 |
| Tests | ~497 |
| Assertions | ~2500 |
## Service Provisioning
| Platform | Service Type | API | Status |
|----------|-------------|-----|--------|
| **VirtFusion** | VPS | REST API | Implemented |
| **Pterodactyl** | Game Servers | REST API | Implemented |
| **SynergyCP** | Dedicated Servers | REST API | Implemented |
| **Enhance** | Web Hosting | REST API | Implemented |
Provisioning is event-driven (triggered by `PaymentSucceeded`), idempotent (`Service::firstOrCreate`), and includes automatic retry every 5 minutes via `RetryProvisioningCommand`.
## Support System
Built as a standalone ticket system (not SupportPal):
- Ticket model with replies, departments, priorities, and statuses
- Customer pages: create, view, reply, close tickets
- Admin pages: list (filterable), view, reply, update status
- IMAP email integration: inbound email creates/replies to tickets automatically
- Email threading with `[EZSCALE-{id}]` references in subject lines
- Scheduled `tickets:process-emails` command polls IMAP every 2 minutes
## Payment Gateways
### Payment Gateways
| Gateway | Usage | Integration | | Gateway | Usage | Integration |
|---------|-------|-------------| |---------|-------|-------------|
| **Stripe** | Primary (~80%) | Laravel Cashier v16 | | **Stripe** | Primary | Laravel Cashier |
| **PayPal** | Secondary (~20%) | srmklive/laravel-paypal | | **PayPal** | Secondary | srmklive/paypal |
| **Crypto** | Optional | Coinbase Commerce |
## Database Overview ## API
### Core Tables ### Customer API (Passport auth, `/api/v1/`)
- **Users & Auth**: users, user_profiles, roles, permissions, audit_logs, login_history - Services: list, detail, reboot (VPS)
- **Billing**: plans, subscriptions, invoices, payment_transactions, coupons, account_credits - Invoices: list (filterable), PDF download
- **Services**: services, provisioning_logs, bandwidth_usage, backups - Subscriptions: list, cancel
- **Support**: support_tickets (mirrored), announcements - Tickets: list, create, detail with replies, reply
- **Team**: team_members, team_invitations
- **Monitoring**: uptime_checks, uptime_incidents, status_components
- **Abuse**: abuse_reports, abuse_actions
- **Communication**: customer_timeline, webhook_deliveries
- **Network**: ip_addresses, datacenters
See **PROJECT_DEVELOPMENT.md** for complete schema with all columns. ### Admin API (Passport auth + admin role, `/api/v1/admin/`)
- Customers: list (searchable/filterable), detail
- Services: list (filterable), detail, suspend, unsuspend
- Analytics: MRR, ARR, churn, growth, revenue by month/type
## WHMCS Migration Rate limiting: 60 requests/min (customer), 120 requests/min (admin). All admin API actions are audit-logged.
### Scope
- Full historical data migration (100-1000 customers)
- All invoices, payments, services, subscriptions
- Automated migration scripts (Laravel commands)
- 30-day parallel operation period
- Redirect old WHMCS URLs to new platform
### Migration Commands
Run from the `website/` directory:
```bash
cd website
php artisan migrate:whmcs-customers # Import customers and profiles
php artisan migrate:whmcs-subscriptions # Import active subscriptions
php artisan migrate:whmcs-invoices # Import invoice history
php artisan migrate:whmcs-payments # Import payment history
php artisan migrate:whmcs-services # Import service configurations
php artisan migrate:whmcs-tickets # Migrate tickets to SupportPal
```
## Security ## Security
### Authentication ### Authentication
- **Customer**: Email + password, optional 2FA (TOTP/passkeys) - **Customer**: Email + password, optional 2FA (TOTP)
- **Admin**: Email + password + required 2FA (passkeys preferred) - **Admin**: Email + password + 2FA
- **Admin Panel**: Behind Cloudflare Zero Trust access control - **Admin Panel**: Planned Cloudflare Zero Trust access control
- **API**: Laravel Sanctum token authentication - **API**: Laravel Passport token authentication
### Data Protection ### Data Protection
- Service credentials encrypted at rest - Service credentials encrypted at rest
- HTTPS enforced everywhere - CSRF protection on all forms (webhooks exempted)
- CSRF protection on all forms - Rate limiting on auth and API endpoints
- Rate limiting on auth and API
- SQL injection prevention (Eloquent ORM) - SQL injection prevention (Eloquent ORM)
- XSS prevention (Blade/Vue escaping + CSP) - XSS prevention (Vue escaping)
### Compliance
- GDPR-compliant automated data deletion
- Full audit trail of admin actions - Full audit trail of admin actions
- Login history with IP tracking - Login history with IP tracking and new-device notifications
- Fraud detection on signup - Trusted device management for 2FA
- Abuse management system
## Performance & Scalability
### Caching Strategy
- Real-time: Today's revenue, active orders
- 15-min cache: Historical analytics
- Daily aggregation: Month/year totals
### Queue System
- **Critical queue**: Provisioning, payments, suspension
- **Normal queue**: Emails, notifications, backups
- **Low queue**: Analytics, reports, cleanup
### Scaling
- Cloudflare CDN + WAF + DDoS protection
- Load balancer with auto-scaling
- Multi-region database replication
- 15-minute backup RPO
## API
### Customer API (Full Control)
- Create, modify, delete services
- View invoices and billing history
- Manage payment methods
- Check bandwidth usage
- Reboot/manage servers
### Webhook Support
- Customers can register webhook URLs
- Events: `invoice.created`, `service.provisioned`, `bandwidth.threshold_reached`, etc.
- HMAC signature verification
- Automatic retry on failure
### Custom Domains
- Customers can point `billing.theirdomain.com` to platform
- Auto-provisioned SSL via Let's Encrypt
- DNS verification required
## Analytics & Reporting ## Analytics & Reporting
### Admin Dashboard ### Admin Dashboard
- MRR (Monthly Recurring Revenue) - MRR and ARR tracking
- ARR (Annual Recurring Revenue) - Churn rate calculation and trends
- Churn rate and customer growth - Customer growth chart
- Revenue trends (daily, monthly, yearly) - Revenue trends (daily, monthly, yearly)
- Popular plans and conversion rates - Popular plans and overdue invoices
- Outstanding invoices
### Financial Reports ### Financial Reports
- Revenue reports (by period, service, plan) - Revenue reports (by period, service type, plan)
- Profit & Loss statements - Profit & Loss statements
- Tax reports (sales tax, VAT) - Tax reports (sales tax, VAT)
- Aging reports (overdue invoices) - Aging reports (overdue invoices)
- Refund reports - Refund reports
- Subscription metrics - Subscription metrics
- Export: PDF, CSV, JSON
## Quick Start
```bash
cd website
composer install
npm install
cp .env.example .env
php artisan key:generate
# Configure .env (database, Stripe keys, etc.)
php artisan migrate
php artisan db:seed
# Development
composer run dev # Starts artisan serve + queue + pail + vite
```
See **GETTING_STARTED.md** for the full development setup guide.
## Project Layout ## Project Layout
The Laravel 12 application is located in the **`website/`** directory (base install, no additional packages yet). Documentation and planning files are in the repository root. ```
website/
├── app/
│ ├── Models/ # 29 Eloquent models
│ ├── Http/Controllers/ # Account/, Admin/, Api/V1/ controllers
│ ├── Http/Resources/ # API Resources
│ ├── Services/Billing/ # Stripe, PayPal, Dunning services
│ ├── Events/ # Payment, Subscription events
│ ├── Listeners/ # Event handlers
│ └── Console/Commands/ # RetryProvisioning, SyncStripePrices, etc.
├── database/
│ ├── migrations/ # 59 migrations
│ ├── factories/ # 24 factories
│ └── seeders/ # Roles, plans, admin, demo data
├── resources/
│ ├── ts/ # TypeScript source
│ │ ├── Pages/ # 85 Vue pages
│ │ ├── Components/ # 26 Vue components
│ │ ├── Layouts/ # Account, Admin, Auth, Marketing
│ │ ├── stores/ # Pinia stores
│ │ ├── types/ # TypeScript interfaces
│ │ └── plugins/vuetify/ # Theme, defaults, icons
│ └── styles/ # Custom EZSCALE design system (SCSS)
├── routes/ # web, account, admin, marketing, webhooks, api
├── tests/ # 43 test files (~497 tests)
└── scripts/whmcs-migrate/ # WHMCS migration scripts (WIP)
```
**Important**: This machine is for documentation and planning only. The actual project building and code execution happens on a separate development machine. ## WHMCS Migration
## Contact Migration from WHMCS is planned for the launch phase. Migration scripts are in `scripts/whmcs-migrate/`. The migration will cover customers, subscriptions, invoices, payment history, services, and tickets. A 30-day parallel operation period is planned.
For questions about this project, contact the EZSCALE development team.
--- ---
**Status**: Base Laravel 12 install in `website/` - Ready for Phase 1 Development **Status**: Active Development — Phases 1-5, 8-9 complete, Phase 10 in progress
**Last Updated**: February 9, 2026 **Last Updated**: March 16, 2026
**Total Planning Documents**: 7 files, ~4000+ lines of specifications **Total Documentation**: 9 files, ~5900 lines of specifications