# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Overview

Laravel 10 backend for a VPS/hosting SaaS platform. Provides an admin panel (Livewire), a customer REST API (JWT), and an admin REST API (JWT + Passport), with deep VMware vCenter integration for VM provisioning.

---

## Common Commands

```bash
# Dev server
php artisan serve

# Migrations & seeding
php artisan migrate
php artisan db:seed --class=SomeSeeder

# Clear all caches
php artisan cache:clear && php artisan config:clear && php artisan route:clear && php artisan view:clear

# Queue
php artisan queue:work
php artisan horizon

# Tests
php artisan test
php artisan test tests/Feature/SomeTest.php
php artisan test --filter testMethodName

# Swagger docs regeneration
php artisan l5-swagger:generate
```

---

## Routing

Four route files, each serving a different audience:

| File | Domain/Prefix | Auth | Audience |
|------|---------------|------|----------|
| `routes/admin.php` | `admin.portal.test` | Session (`auth` + `Staff`) | Admin panel web UI |
| `routes/api.php` | `/api/v1/administrator/` | JWT (`admins-api` guard) | Admin REST API |
| `routes/client.php` | `/api/v1/client/` | JWT (`client` guard) | Customer REST API |
| `routes/web.php` | `/` | None | Public pages |

**Middleware aliases:**
- `Staff` → `StaffCheck` — enforces admin session, updates `last_visited`
- `api.auth` → `ApiAuthCheck` — JWT validation, returns JSON 401 on failure
- `LoginCheck` — redirects authenticated users away from login page

---

## Architecture

### Controller Layers

```
app/Http/Controllers/
├── admin/          — Admin panel web controllers (Blade/Livewire views)
├── Api/Admin/      — Admin REST API controllers
├── Api/Client/     — Customer REST API (ClientController)
├── Api/Service/    — Product/order/service endpoints (used by both)
├── Api/Transaction/— Payment and transaction endpoints
└── rest/           — Legacy internal REST endpoints
```

### Repository Pattern

All DB access goes through repositories. Never query models directly in controllers.

```
app/Repositories/{Domain}/
├── {Domain}Repository.php          — Concrete (extends BaseRepository)
├── {Domain}RepositoryInterface.php — Interface
└── {Domain}CachedRepository.php   — Redis-cached variant (optional)
```

**BaseRepository** provides: `create`, `update`, `delete`, `find`, `getAll`, `getCount`, `insert`.

Repositories are bound in `AppServiceProvider` → `RepositoryProvider` (40+ bindings). Always inject via interface.

### Service Layer

Business logic is split across two locations:

- `app/Services/` — Domain services: `VMDataService`, `VMHelperService`, `WhoisService`
- `app/Http/Services/` — HTTP-integration services:
  - `vCenter.php` — VMware vCenter REST API wrapper (Guzzle, SSL disabled for self-signed certs). Key methods: `loginServer()`, `GetConsoleTickets()`, `getAllVirtualMachine()`, `checkApiExits()`. Token stored in model, refreshed on 'Login_Again' response.
  - `WinRMClient.php` — Windows Remote Management for VM operations
  - `VNPayService.php` — Payment gateway
  - `Invoice/` — Invoice generation/processing
  - `PusherNotification.php`, `Telegram.php`, `Discord.php` — Notifications

Dedicated admin service layer: `app/Services/Api/Admin/` (`ProductService`, `VCenterService`), `app/Services/Api/` (`ClientAuthService`, `ServiceService`).

### Global Helpers

`app/Http/Helpers/function_helper.php` (auto-loaded via Composer):
- `setting('group.key')` — Read cached settings with dot notation
- `format_price(amount)` — Format as ₫ currency
- `format_point(points)` — Format loyalty points
- `format_day(date, format)` — Date formatting

### Enums

Type-safe PHP enums in `app/Enums/{Domain}/`. Support `label()` for Vietnamese display text. Key enums: `InvoiceStatus`, `ProductTypeEnums`, `TransactionStatus`, `Status`, `AddonType`.

### Admin UI

Livewire 3 components in `app/Http/Livewire/`. Modal pattern uses Alpine.js events:
- Open: `$dispatch('open-{modal-name}')` / listen with `@open-{modal-name}.window`
- Close: `$dispatch('close-{modal-name}')` / listen with `@close-{modal-name}.window`

Server-side tables use Yajra DataTables.

---

## Auth Guards

| Guard | Driver | Used By |
|-------|--------|---------|
| `web` / `admins` | session | Admin panel |
| `admins-api` | JWT (tymon/jwt-auth) | Admin REST API |
| `client` | JWT (tymon/jwt-auth) | Customer API (portal-client) |
| `users-api` | Passport OAuth2 | — |
| `client-sanctum` | Sanctum | Alternative customer auth |

---

## Key Models

**Core business:** `Customer` (UUID PK, JWT subject), `Order`, `Invoice` (InvoiceStatus enum), `InvoiceItem`, `Product` (slug, cpu/ram/disk/bandwidth/gpu specs), `ProductCategories` (hierarchical via kalnoy/nestedset).

**VMware:** `vCenter` (credentials + token), `ModuleVmware` (VM instances → orders), `ModuleHost`, `ModuleDatacenter`, `ModuleNetwork`, `ModuleIpAddress`, `ModuleDatastore`, `ModuleSnapshot`.

**Finance:** `Transaction`, `Payment`, `Cart`, `CartAddon`.

**Support:** `Ticket`, `TicketReply`, `Mail`.

---

## Queue Jobs

Async operations in `app/Jobs/`:
- `VirtualMachine/ProcessOrderPaymentJob` — Payment processing + VM provisioning
- `Hosting/`, `Mail/`, `Ticket/`, `Payment/` — Domain-specific async tasks

---

## API Response Convention

```json
{ "error": false, "data": {...} }
{ "error": true, "message": "Reason here" }
```

API Resources in `app/Http/Resources/Api/` transform models before response.

---

## Key Integrations

- **VMware vCenter** — `app/Http/Services/vCenter.php`, passwords decrypted via `SignRSA` facade
- **VNPay** — `config/vnpay.php`, `VNPayService.php`
- **Redis** — Caching (cached repositories), sessions, queues
- **Pusher** — Real-time events
- **CKFinder** — Admin file browser (custom auth: `CustomCKFinderAuth` middleware)
- **L5-Swagger** — API docs at `/api/documentation`
- **Spatie Permission** — RBAC for admin roles
- **Horizon** — Queue monitoring at `/horizon`