diff --git a/CLAUDE.md b/CLAUDE.md index e1d734b..f131c4f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,38 +1,28 @@ # CLAUDE.md - EZSCALE Site ## 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) 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 --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. +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 (`gh issue comment --body "Completed X"`). +3. **After completing:** Update `TASKS.md` to check off completed items and close the corresponding GitHub issue. +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)`). 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 --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 +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 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 -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) +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. @@ -40,241 +30,154 @@ The Laravel application is in **`website/`**. All artisan, composer, and npm com ``` 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.) +│ ├── Models/ # 29 Eloquent models +│ ├── Http/Controllers/ # Account/, Admin/, Api/V1/ controllers +│ ├── Http/Resources/ # API Resources │ ├── 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 +│ ├── 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 (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 +│ ├── 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), 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 -- **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) +- **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, 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) - **Roles:** spatie/laravel-permission (admin, customer) -- **Queue:** Laravel Horizon for queue management +- **Queue:** Laravel Horizon ## 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. +**All frontend code MUST use TypeScript.** -### Rules - All `.vue` files must use ` -``` - ## 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 +- **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 (via Bunny Fonts CDN) -- **Code font:** JetBrains Mono (via Bunny Fonts CDN) +- **UI font:** Plus Jakarta Sans (Bunny Fonts CDN) +- **Code font:** JetBrains Mono (Bunny Fonts CDN) ### Key Patterns -- **Component structure:** `