diff --git a/CLAUDE.md b/CLAUDE.md index b774635..4278f55 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,73 +1,93 @@ -# CLAUDE.md - EZSCALE Site Project Instructions +# CLAUDE.md - EZSCALE Site -## Important Context -- This repository is used for **documentation and planning only** on this machine -- Actual project building and code execution happens on a separate development machine -- Do NOT attempt to run composer, php, node, or other build commands here -- Focus on documentation, architecture, and planning tasks +## Project +EZSCALE Site — Laravel 12 application replacing WHMCS for VPS/Dedicated Server hosting management (billing, subscriptions, provisioning, customer management, SSO). -## Project Overview -EZSCALE Site is a Laravel 12 application replacing WHMCS for VPS/Dedicated Server hosting management. It handles billing, subscriptions, provisioning, customer management, and 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+) -- **Frontend:** Vue 3 + Inertia.js + Tailwind CSS -- **UI Theme:** Vuexy VueJS + Laravel Admin Dashboard Template (source files to be added) -- **Payments:** Laravel Cashier Stripe (primary) + srmklive/laravel-paypal (secondary) -- **Database:** MySQL 8.x -- **Queue:** Redis -- **Auth:** Laravel Fortify + Passport (OAuth2/SSO) -- **Roles:** spatie/laravel-permission +- **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) -## Project Structure -``` -app/ -├── Models/ # Eloquent models -├── Http/ -│ ├── Controllers/ # Route controllers -│ ├── Middleware/ # Custom middleware -│ └── Requests/ # Form request validation -├── Services/ # Business logic (provisioning, billing, etc.) -├── Policies/ # Authorization policies -└── Events/ # Domain events -``` - -## Development Commands +## Commands ```bash -php artisan serve # Run dev server -php artisan test # Run test suite -php artisan migrate # Run migrations -php artisan queue:work # Process queue jobs -npm run dev # Vite dev server -npm run build # Production build +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 -- Follow PSR-12 coding standards -- Use strict typing: `declare(strict_types=1);` in all PHP files -- Use Form Request classes for validation -- Use Service classes for business logic (not in controllers) -- Use Policies for authorization -- Use Events/Listeners for side effects (email, provisioning, etc.) -- Write Feature and Unit tests for all new functionality -- Use database transactions for multi-step operations +- 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 Requirements +## 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 -- Input sanitization on all user inputs - Encrypted storage for sensitive data (API keys, credentials) - Audit logging for admin actions and billing events -## Key Domains -1. **Billing** - Subscriptions, invoices, payments via Cashier -2. **Provisioning** - Server creation, suspension, termination -3. **Customer Management** - Profiles, support tickets, notifications -4. **Admin Panel** - Dashboard, user management, server management -5. **SSO** - Single sign-on across EZSCALE services +## Domains +- **ezscale.cloud** — Marketing site +- **account.ezscale.cloud** — Customer dashboard +- **admin.ezscale.cloud** — Admin panel (Cloudflare Zero Trust) +- **status.ezscale.cloud** — Public status page -## Reference Files -- `TASKS.md` - Current task list and progress -- `PROJECT_DEVELOPMENT.md` - Architecture decisions and development plan +## 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) diff --git a/GETTING_STARTED.md b/GETTING_STARTED.md index 3f2b2a0..12fc323 100644 --- a/GETTING_STARTED.md +++ b/GETTING_STARTED.md @@ -25,30 +25,24 @@ This guide will help you start building the EZSCALE Billing Platform on your dev # Clone the repository git clone git@github.com:EZSCALE/accounting.git ezscale_billing cd ezscale_billing +``` + +The Laravel 12 application is already installed in the `website/` directory as a **base install** (no additional packages or customizations yet). + +## Step 2: Navigate to Laravel Directory + +```bash +# All Laravel commands run from the website/ directory +cd website # Create develop branch git checkout -b develop ``` -## Step 2: Initialize Laravel 12 Project - -Since this is currently just documentation, you'll initialize a fresh Laravel 12 project: - -```bash -# Install Laravel 12 with Vue + Inertia starter kit -composer create-project laravel/laravel . - -# During installation, select: -# - Starter kit: Vue + Inertia -# - Testing framework: Pest -# - Database: MySQL -``` - ## Step 3: Configure Environment ```bash -# Copy the planning files (already in repo) -# .env file should already exist, update it: +# The .env file is in website/ - update it: APP_NAME="EZSCALE Billing" APP_ENV=local @@ -102,8 +96,15 @@ EXIT; ## Step 5: Install Dependencies +All commands below should be run from the `website/` directory: + ```bash -# Install PHP dependencies +cd website + +# Install base PHP dependencies (already in composer.json from base install) +composer install + +# Install additional PHP dependencies for the project composer require laravel/cashier composer require laravel/fortify composer require laravel/passport @@ -119,8 +120,8 @@ npm install ```bash # Extract Vuexy theme source files to: -# resources/js/vuexy/ -# resources/css/vuexy/ +# website/resources/js/vuexy/ +# website/resources/css/vuexy/ # Update vite.config.js to include Vuexy assets # Update app.js to import Vuexy components @@ -185,7 +186,11 @@ php artisan passport:install ## Step 10: Start Development Servers +All commands below should be run from the `website/` directory: + ```bash +cd website + # Terminal 1: Start Laravel server php artisan serve @@ -235,6 +240,9 @@ php artisan test # Pull latest changes git pull origin develop +# Navigate to Laravel directory +cd website + # Install any new dependencies composer install npm install @@ -281,7 +289,7 @@ php artisan test --coverage Use this checklist to track Phase 1 Foundation progress: -- [ ] Laravel 12 project initialized +- [x] Laravel 12 project initialized (base install in `website/`) - [ ] Vuexy theme integrated - [ ] Environment configured (.env) - [ ] Database created and connected diff --git a/KASM_AND_MULTITENANCY.md b/KASM_AND_MULTITENANCY.md index 30a546c..4461a09 100644 --- a/KASM_AND_MULTITENANCY.md +++ b/KASM_AND_MULTITENANCY.md @@ -554,7 +554,11 @@ Each tenant gets a complete copy of the main application schema: ### Installation & Setup +All commands below should be run from the `website/` directory: + ```bash +cd website + # Install Tenancy for Laravel composer require stancl/tenancy diff --git a/PROJECT_DEVELOPMENT.md b/PROJECT_DEVELOPMENT.md index 0fdd872..6a9778b 100644 --- a/PROJECT_DEVELOPMENT.md +++ b/PROJECT_DEVELOPMENT.md @@ -433,7 +433,7 @@ announcements ## 8. Development Phases ### Phase 1: Foundation & Core Setup -- Initialize Laravel 12 with Vue + Inertia starter kit +- ~~Initialize Laravel 12 with Vue + Inertia starter kit~~ ✓ (base install in `website/`) - Configure domains: ezscale.cloud, account.ezscale.cloud, admin.ezscale.cloud - Set up MySQL with replication, Redis - Install dependencies: Cashier, Fortify, Passport, PayPal, Spatie diff --git a/README.md b/README.md index c5b81eb..46dcfd4 100644 --- a/README.md +++ b/README.md @@ -10,13 +10,16 @@ Modern Laravel 12 billing and customer management platform replacing WHMCS for E | File | Purpose | Lines | |------|---------|-------| -| **CLAUDE.md** | Project instructions for AI assistance | ~70 | +| **CLAUDE.md** | Project instructions for AI assistance | ~80 | | **PROJECT_DEVELOPMENT.md** | Complete architecture & development plan | ~600 | | **TASKS.md** | Detailed task breakdown (13 phases) | ~400 | | **FEATURES.md** | Feature specifications (35+ features) | ~1000 | | **KASM_AND_MULTITENANCY.md** | Kasm Workspaces + Multi-Tenancy implementation | ~600 | | **GETTING_STARTED.md** | Development setup guide | ~300 | +| **ADVANCED_FEATURES.md** | Advanced feature specifications (28 features) | ~1400 | +| **IDEAS.md** | Future feature ideas and exploration topics | ~500 | | **README.md** | This file - project overview | - | +| **website/** | Laravel 12 base installation | - | ## Quick Overview @@ -70,9 +73,9 @@ A comprehensive billing and service management platform for EZSCALE Hosting that - ✅ Full audit trail and login history - ✅ Unified communication timeline -## Current Status: Planning Phase +## Current Status: Base Install Complete -We are currently in the **documentation and planning phase**. This repository contains comprehensive planning documents but no code yet. +The **Laravel 12 base installation** exists in the `website/` directory. Planning and documentation is complete. No additional packages or customizations have been added yet. ### Planning Complete ✓ - [x] Infrastructure architecture designed @@ -83,11 +86,12 @@ We are currently in the **documentation and planning phase**. This repository co - [x] Task breakdown completed (200+ tasks) - [x] Security architecture defined - [x] WHMCS migration strategy planned +- [x] Laravel 12 base install created (`website/`) ### Next Steps -1. Review and approve planning documents -2. Set up development environment on separate machine -3. Initialize Laravel 12 project with Vue + Inertia +1. Install core dependencies (Cashier, Fortify, Passport, PayPal, Spatie) +2. Configure environment and database +3. Create database schema and migrations 4. Begin Phase 1: Foundation (auth, database, core setup) ## Development Phases @@ -157,7 +161,9 @@ See **PROJECT_DEVELOPMENT.md** for complete schema with all columns. - 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 @@ -245,9 +251,11 @@ php artisan migrate:whmcs-tickets # Migrate tickets to SupportPal - Refund reports - Subscription metrics -## Development Machine +## Project Layout -**Important**: This machine is for documentation and planning only. The actual Laravel project will be built on a separate development machine. +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. + +**Important**: This machine is for documentation and planning only. The actual project building and code execution happens on a separate development machine. ## Contact @@ -255,6 +263,6 @@ For questions about this project, contact the EZSCALE development team. --- -**Status**: Planning Phase - Documentation Complete -**Last Updated**: February 8, 2026 -**Total Planning Documents**: 4 files, ~2000 lines of specifications +**Status**: Base Laravel 12 install in `website/` - Ready for Phase 1 Development +**Last Updated**: February 9, 2026 +**Total Planning Documents**: 7 files, ~4000+ lines of specifications diff --git a/TASKS.md b/TASKS.md index ac7e780..ceb94c6 100644 --- a/TASKS.md +++ b/TASKS.md @@ -1,7 +1,7 @@ # TASKS.md - EZSCALE Site Task Tracker ## Phase 1: Foundation & Core Setup -- [ ] Initialize Laravel 12 project with Vue + Inertia starter kit +- [x] Initialize Laravel 12 project with Vue + Inertia starter kit (base install in `website/`) - [ ] Configure domain routing (ezscale.cloud, account.ezscale.cloud, admin.ezscale.cloud) - [ ] Set up MySQL 8.x with multi-region replication and automated backups - [ ] Configure Redis (cache, queue, sessions)