# CLAUDE.md

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

## Commands

### Development
```bash
# Start Vite dev server (asset compilation with HMR)
npm run dev

# Build assets for production
npm run build

# Start Laravel development server
php artisan serve
```

### Database
```bash
php artisan migrate
php artisan migrate:fresh --seed
```

### Testing
```bash
# Run all tests
php artisan test

# Run a single test file
php artisan test tests/Feature/Auth/LoginTest.php

# Run tests with coverage
php artisan test --coverage
```

### Code Style
```bash
# Format PHP code (Laravel Pint)
./vendor/bin/pint
```

## Architecture Overview

This is a **Laravel 11** financial/investment management admin dashboard. PHP 8.2+, with Vite + Tailwind CSS + Alpine.js on the frontend.

### Key Packages
- **Spatie Laravel Permission** (`spatie/laravel-permission`) — role-based access control; roles are checked via `isBackOfficeUser()`, `isClientAdministrator()`, `currentUserRole()` helpers in `app/helpers.php`
- **Laravel Cashier** (`laravel/cashier`) — Stripe billing; User model uses `Billable` trait
- **Laravel Socialite** — social login (Google)
- **Yajra DataTables** — server-side data tables in views
- **Maatwebsite Excel** — data export/import via classes in `app/Exports/`
- **lab404/laravel-impersonate** — admin can impersonate users
- **vinkla/hashids** — obfuscated IDs in URLs
- **hisorange/browser-detect** — tracks browser/device on login

### Application Structure

**Multi-tenant model**: The app is organized around `Client` entities. Most models have a `client_id` foreign key. The `currentClientId()` helper returns the active client context. Back-office users (admins) can access all clients; regular users are scoped to their client.

**User roles**: Defined via Spatie permissions. Key helpers: `isBackOfficeUser()` (admin), `isBackOfficeRole()`, `isClientAdministrator()`. The `User` model includes two-factor authentication, soft deletes, and activity logging (via `LogsActivity` trait).

**Service layer**: Business logic lives in `app/Services/`. Notable: `FacturaService.php` handles invoice/billing integration; `app/Services/Auth/` handles authentication flows.

**Routes**: Defined in `routes/web.php` (main) and `routes/auth.php` (authentication). Routes are grouped by module with ~30+ controllers covering: Dashboard, Users, Payments, Invoices, Quotes, Projects, Services, Bank Operations, Reports, Subscriptions.

**Views**: Blade templates in `resources/views/`. Reusable UI components are in `app/View/Components/` with corresponding views.

**Localization**: English and Spanish translations in `lang/en/` and `lang/es/`.

**Custom config files**: `config/factura.php` (invoicing), `config/hashids.php` (ID obfuscation).

### Core Models
`User`, `Client`, `Invoice`, `Payment`, `Payout`, `Investment`, `Package`, `Bank`, `Account`, `Operation`, `Project`, `Quote`, `Service`, `Subscription`, `Commission`, `Transfer`, `Expense`, `Contact`, `Category`, `Concept`

### Frontend
Assets compiled by Vite (`vite.config.js`). Entrypoints are in `resources/`. Tailwind CSS configured in `tailwind.config.js`. Alpine.js is used for interactive UI components inline in Blade templates.

### Testing
Uses **Pest PHP**. Tests live in `tests/Feature/` (integration) and `tests/Unit/`. The `tests/Pest.php` file configures Pest. Test environment uses SQLite in-memory, array cache, and sync queue (set in `phpunit.xml`).