# CLAUDE.md

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

## Project Overview

Angolan web-hosting and IT-services management platform (Laravel 12). Clients order hosting plans, domains, and services; admins manage billing, subscriptions, and server config. Primary language is **Portuguese (pt)**; UI strings live in `lang/pt/`.

## Commands

```bash
# Development (runs artisan serve + queue:listen + npm dev concurrently)
composer dev

# Or individually:
php artisan serve
php artisan queue:work
npm run dev

# Build assets for production
npm run build

# Run all tests
php artisan test

# Run migrations
php artisan migrate

# Format code
./vendor/bin/pint
```

## Architecture

- **Blade + Livewire 3** for admin/client panels (`app/Livewire/Admin/`, `app/Livewire/Client/`); business logic lives in Livewire components, not controllers
- **Livewire Volt** (file-based components) for public-facing pages under `resources/views/livewire/`
- **REST API** (`routes/api.php`) for a separate frontend; auth via Laravel Sanctum
- **Queue jobs** (`app/Jobs/`) drive the subscription lifecycle: activation, suspension, domain locking, EEP requests
- **No `app/Http/Kernel.php` / `app/Console/Kernel.php` / `app/Exceptions/Handler.php`** — Laravel 11+ style; middleware/exceptions configured in `bootstrap/app.php`; scheduled commands in `routes/console.php`
- Site-wide settings are key/value rows in `definicaos` table via the `Definicao` model
- **PDF invoices/proformas**: `barryvdh/laravel-dompdf` via `app/Http/Controllers/pdfController.php`
- **Excel imports**: `maatwebsite/excel` in `app/Imports/`
- **Charts**: `arielmejiadev/larapex-charts` (ApexCharts) in `app/Charts/`

## Conventions

- **Admin routes** prefixed `/admin/*`; **client routes** prefixed `/client/*` — see `routes/web.php`
- Portuguese naming throughout: models (`Pedidos`, `Servico`, `Susbscricao`), columns (`preco_iva`, `telefone`, `endereco`), routes (`/dominios`, `/hospedagem`)
- Subscription tables use the intentional typo spelling `susbscricao` (not `subscricao`) — preserve this in any new migrations or models
- Order codes follow pattern `ENC001/2024` — see `Pedidos` model for generation logic
- IVA (VAT) is a first-class concern; every `Servico` carries `preco`, `preco_iva`, and `iva` fields; the `Iva` model holds configurable rates
- Discount logic is in `app/Models/Desconto.php` and `app/Models/UserDesconto.php`
- Email templates are configurable via `descricao_mails` table; see `app/Mail/` for Mailable classes
- `routes/api.php` defines a global helper `email()` wrapped in `if (!function_exists('email'))` — do not remove that guard
- NIF lookup scrapes Angola's `minfin.gov.ao` portal via `POST /api/scrap/`

## Integrations

- **cPanel API** — `app/Models/Cpanel.php`, `app/Jobs/ActivarConta.php`
- **PTISP (Angolan domain registrar)** — `app/Jobs/Ptisp.php`, `app/Models/Dominio.php`
- Domain locking and EEP (transfer) requests handled by `app/Jobs/LockDomain.php` and `app/Jobs/SolicitarEEP.php`

## Security Notes

- Admin and client areas require `auth` middleware — do not add public routes to those groups
- Sanctum protects all order-creation and account-data API endpoints
- The `bi_nif` (national ID / tax number) field on `User` is sensitive PII — avoid logging or exposing it