=== .ai/project-description rules === # CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Runtime environment This service runs inside the `polaris-service-new` Docker container. Run Artisan/Composer/PHPUnit/Pint commands inside the container, not on the host: ```bash docker exec -i polaris-service-new php artisan docker exec -i polaris-service-new vendor/bin/pint --dirty # format dirty files before finalizing docker exec -i polaris-service-new php artisan test --compact docker exec -i polaris-service-new php artisan test --compact --filter= ``` Always run `vendor/bin/pint --dirty` before finalizing changes; don't use `pint --test`. The `laravel-boost` MCP server is wired up to exec into this container (`.mcp.json`) — its `tinker`, `database-query`, `list-artisan-commands`, `search-docs`, `read-log-entries`, etc. are the preferred way to inspect/interact with the running app. Use `search-docs` for Laravel/Livewire/ecosystem docs (it auto-filters by installed versions) before falling back to web search. Frontend assets use Vite (`npm run dev` / `npm run build`). The frontend surface is small; most UI is server-rendered via Livewire + OpenAdmin Blade views. If a frontend change isn't visible, the user may need to run `npm run dev` / `npm run build`. ## Stack versions (pinned) PHP 8.3 · Laravel 10 · Livewire 3 · Sanctum 3 · Scout 10 (Elasticsearch engine) · Pulse 1 · Pint 1 · PHPUnit 10. Postgres (primary) + Redis + Elasticsearch + several MySQL/SQL Server external DBs. ## Multi-instance architecture (read this first) This single codebase is deployed as three separate instances — **Peru**, **Colombia**, and **Mexico** — selected at runtime by the `APP_INSTANCE` env var. Almost every non-trivial subsystem branches on instance. Do not assume a feature works the same across all three; check. **Discovering instance-conditional code:** - Helper predicates in `app/Helpers/Autoload/functions.php`: `isPeru()`, `isColombia()`, `isMexico()`, `getInstance()`, `getCountryPhoneCode()`, `toCurrency()`, `toPhone()`, `toDate()` — all format/behave differently per instance. - Constants in `app/Helpers/Autoload/constants.php`: `INSTANCE_PERU`, `INSTANCE_COLOMBIA`, `INSTANCE_MEXICO`, plus `PERMISSION_*` slugs (Spanish, e.g. `historial-de-sms`). - Both files are autoloaded via `composer.json` → `autoload.files`, so the helpers/constants are globally available. - `AppServiceProvider::register()` binds abstract handlers (`AbstractDatabaseLoanUpdateHandler`, `AbstractDatabasePaymentUpdateHandler`, `AbstractPaymentPeriodsHandler`, `CommunicationMigratorContract`, ...) to per-instance concrete classes via `match(config('polaris.instance'))`. When adding a new actualization/migration variant, register it here. - `app/Console/Kernel.php` schedules commands per instance via the `LEAD_TIME` constant keyed by `INSTANCE_*`. Cron schedules are *not* in `schedule()` directly — add entries to `LEAD_TIME[INSTANCE_X]` and the loop wires them up with `withoutOverlapping(10)` by default (override via `COMMAND_SETTINGS`). When in doubt, grep for `isPeru\|isColombia\|isMexico\|INSTANCE_` before changing behavior. ## Database connections `config/database.php` defines many connections; app code targets named connections explicitly. The important ones: - **`collection`** (PostgreSQL, `search_path=collector_drpeso`) — main app schema (loans, payments, calls, communications). `collection_replica` is the read replica. - **`users`** (PostgreSQL, `search_path=collector_usuarios_drpeso`) — user/auth/permissions schema. - **`sms`**, **`email`** (PostgreSQL, separate `search_path`s on the same DB) — SMS/email history and templates. - **`mysql`** (legacy MySQL `collector_drpeso`) — used by older actualization SQL files at the repo root (`01_…sql` … `06_…sql`). - **`mx_crm`** (MySQL), **`col_crm`** (SQL Server), **`issabel`**, **`vicidial`** (MySQL) — external integrations for actualization/communication migration. Read-only from this app's perspective. Models live under `app/Models/` grouped by schema (`Collection/`, `Sms/`, `Email/`, `User/`, `Shared/`). Eloquent models declare their `$connection` — preserve that when editing/copying. Several connections point at the same Postgres DB with different `search_path`s, so picking the wrong connection silently queries the wrong schema. ## High-level structure - **`app/Admin/`** — OpenAdmin (`open-admin-org/open-admin`) panel. `app/Admin/routes.php` is the admin route file (loaded by the OpenAdmin package, *not* by `routes/web.php`). Most user-facing UI lives here, with controllers thin and the actual UI implemented as Livewire components. - **`app/Livewire/`** — Livewire 3 components grouped by feature (Communication, Sms, Email, Actualization, Search, Setting, Dashboard, …). Note: Livewire 3 namespace is `App\Livewire`, *not* `App\Http\Livewire`. Use `wire:model.live` for real-time updates (`wire:model` is deferred in v3); dispatch events with `$this->dispatch()`; layouts at `components.layouts.app`. Alpine is bundled with Livewire — don't include it separately. - **`app/Http/Controllers/`** — Non-admin HTTP controllers (API + webhooks + a few public endpoints). `routes/api.php` and `routes/webhooks.php` mount them. `routes/web.php` only contains a redirect to `/admin/dashboard` and `/health`. - **`app/Services/`** — - `Actualization/` — periodic sync of loans/payments from external CRMs (DB + file ingestion). Handlers branch per instance (`ColombiaDatabaseLoanUpdateHandler`, `MexicoLoanUpdateHandler`, …). - `Communication/` and `CommunicationIntegrations/` — outbound SMS/email orchestration + provider adapters (Intico, Signos, Vivus, NRS, Mailchimp, SignosTech). Providers are resolved via `SmsProviderFactory` / `EmailProviderFactory` from `ApplicationSettings` (spatie/laravel-settings). - `Company/` — "company" = a campaign/launch; `CommunicationStrategyFactory` builds strategies per channel. - **`app/Integrations/`** — clients for Vicidial and Webitel (telephony). - **`app/Jobs/`** — queued work (Actualization, Communication, Company, Webhook, Loader). `JobsQueueEnum.php` lists the queue names. Use `ShouldQueue` for time-consuming operations. - **`app/Settings/`** — `spatie/laravel-settings` classes (`ApplicationSettings`, …). Settings are stored in DB; migrations for them live in `database/settings/`. - **`config/polaris.php`** — most app-specific configuration (per-instance SMS/email provider credentials, recipient lists, notification toggles, currency formatting). Always read settings via `config('polaris.…')`. ## Routes recap - `routes/web.php` — practically empty (redirect + health). - `routes/api.php` — public/Sanctum-protected API; includes communication dispatch, incoming updates (`loans`, `payments`), tasks, support tickets, SMS/email "launch delivery" endpoints per company, and a Sentry webhook that forwards to Telegram. - `routes/webhooks.php` — external webhook receivers. - `routes/console.php`, `routes/channels.php` — standard. - `app/Admin/routes.php` — the bulk of authenticated UI routes; mounted by OpenAdmin under the prefix from `config('admin.route.prefix')`. ## PHP / Laravel conventions to follow - Always use curly braces for control structures; explicit return types; PHP 8 constructor property promotion. PHPDoc over inline comments — and prefer well-named identifiers over comments at all. - Don't call `env()` outside `config/`. Read settings via `config('polaris.…')` / `config('integrations.…')`. - Don't use `DB::` raw queries — prefer Eloquent `Model::query()` on the right connection. Use proper relationship methods with eager loading to avoid N+1. - Form Request classes for validation, not inline. Check sibling Form Requests for whether array- or string-based rules are used. - For Eloquent casts on Laravel 10, use `protected $casts = [];` (the `casts()` method is Laravel 11+ and is unavailable here). - Use `php artisan make:*` (e.g. `make:test`, `make:livewire`, `make:class`) with `--no-interaction` to create files. - Don't add cron entries directly in `Kernel::schedule()` — extend the `LEAD_TIME` constant in `app/Console/Kernel.php`. - Don't hardcode country-specific formatting (currency, phone, date) — use the `to*()` helpers in `functions.php`, which already branch on instance. ## Tests The `tests/` tree currently only has the default Laravel `ExampleTest.php` stubs — there is no meaningful test coverage. PHPUnit + `php artisan test --compact` are configured (`phpunit.xml`), so new tests work normally. Do not assume an existing test suite will catch regressions; manual/Tinker verification is often necessary. === foundation rules === # Laravel Boost Guidelines The Laravel Boost guidelines are specifically curated by Laravel maintainers for this application. These guidelines should be followed closely to enhance the user's satisfaction building Laravel applications. ## Foundational Context This application is a Laravel application and its main Laravel ecosystems package & versions are below. You are an expert with them all. Ensure you abide by these specific packages & versions. - php - 8.3.6 - laravel/framework (LARAVEL) - v10 - laravel/prompts (PROMPTS) - v0 - laravel/pulse (PULSE) - v1 - laravel/sanctum (SANCTUM) - v3 - laravel/scout (SCOUT) - v10 - livewire/livewire (LIVEWIRE) - v3 - laravel/mcp (MCP) - v0 - laravel/pint (PINT) - v1 - laravel/sail (SAIL) - v1 - phpunit/phpunit (PHPUNIT) - v10 ## Conventions - You must follow all existing code conventions used in this application. When creating or editing a file, check sibling files for the correct structure, approach, and naming. - Use descriptive names for variables and methods. For example, `isRegisteredForDiscounts`, not `discount()`. - Check for existing components to reuse before writing a new one. ## Verification Scripts - Do not create verification scripts or tinker when tests cover that functionality and prove it works. Unit and feature tests are more important. ## Application Structure & Architecture - Stick to existing directory structure; don't create new base folders without approval. - Do not change the application's dependencies without approval. ## Frontend Bundling - If the user doesn't see a frontend change reflected in the UI, it could mean they need to run `npm run build`, `npm run dev`, or `composer run dev`. Ask them. ## Replies - Be concise in your explanations - focus on what's important rather than explaining obvious details. ## Documentation Files - You must only create documentation files if explicitly requested by the user. === boost rules === ## Laravel Boost - Laravel Boost is an MCP server that comes with powerful tools designed specifically for this application. Use them. ## Artisan - Use the `list-artisan-commands` tool when you need to call an Artisan command to double-check the available parameters. ## URLs - Whenever you share a project URL with the user, you should use the `get-absolute-url` tool to ensure you're using the correct scheme, domain/IP, and port. ## Tinker / Debugging - You should use the `tinker` tool when you need to execute PHP to debug code or query Eloquent models directly. - Use the `database-query` tool when you only need to read from the database. ## Reading Browser Logs With the `browser-logs` Tool - You can read browser logs, errors, and exceptions using the `browser-logs` tool from Boost. - Only recent browser logs will be useful - ignore old logs. ## Searching Documentation (Critically Important) - Boost comes with a powerful `search-docs` tool you should use before any other approaches when dealing with Laravel or Laravel ecosystem packages. This tool automatically passes a list of installed packages and their versions to the remote Boost API, so it returns only version-specific documentation for the user's circumstance. You should pass an array of packages to filter on if you know you need docs for particular packages. - The `search-docs` tool is perfect for all Laravel-related packages, including Laravel, Inertia, Livewire, Filament, Tailwind, Pest, Nova, Nightwatch, etc. - You must use this tool to search for Laravel ecosystem documentation before falling back to other approaches. - Search the documentation before making code changes to ensure we are taking the correct approach. - Use multiple, broad, simple, topic-based queries to start. For example: `['rate limiting', 'routing rate limiting', 'routing']`. - Do not add package names to queries; package information is already shared. For example, use `test resource table`, not `filament 4 test resource table`. ### Available Search Syntax - You can and should pass multiple queries at once. The most relevant results will be returned first. 1. Simple Word Searches with auto-stemming - query=authentication - finds 'authenticate' and 'auth'. 2. Multiple Words (AND Logic) - query=rate limit - finds knowledge containing both "rate" AND "limit". 3. Quoted Phrases (Exact Position) - query="infinite scroll" - words must be adjacent and in that order. 4. Mixed Queries - query=middleware "rate limit" - "middleware" AND exact phrase "rate limit". 5. Multiple Queries - queries=["authentication", "middleware"] - ANY of these terms. === php rules === ## PHP - Always use curly braces for control structures, even if it has one line. ### Constructors - Use PHP 8 constructor property promotion in `__construct()`. - public function __construct(public GitHub $github) { } - Do not allow empty `__construct()` methods with zero parameters unless the constructor is private. ### Type Declarations - Always use explicit return type declarations for methods and functions. - Use appropriate PHP type hints for method parameters. protected function isAccessible(User $user, ?string $path = null): bool { ... } ## Comments - Prefer PHPDoc blocks over inline comments. Never use comments within the code itself unless there is something very complex going on. ## PHPDoc Blocks - Add useful array shape type definitions for arrays when appropriate. ## Enums - Typically, keys in an Enum should be TitleCase. For example: `FavoritePerson`, `BestLake`, `Monthly`. === laravel/core rules === ## Do Things the Laravel Way - Use `php artisan make:` commands to create new files (i.e. migrations, controllers, models, etc.). You can list available Artisan commands using the `list-artisan-commands` tool. - If you're creating a generic PHP class, use `php artisan make:class`. - Pass `--no-interaction` to all Artisan commands to ensure they work without user input. You should also pass the correct `--options` to ensure correct behavior. ### Database - Always use proper Eloquent relationship methods with return type hints. Prefer relationship methods over raw queries or manual joins. - Use Eloquent models and relationships before suggesting raw database queries. - Avoid `DB::`; prefer `Model::query()`. Generate code that leverages Laravel's ORM capabilities rather than bypassing them. - Generate code that prevents N+1 query problems by using eager loading. - Use Laravel's query builder for very complex database operations. ### Model Creation - When creating new models, create useful factories and seeders for them too. Ask the user if they need any other things, using `list-artisan-commands` to check the available options to `php artisan make:model`. ### APIs & Eloquent Resources - For APIs, default to using Eloquent API Resources and API versioning unless existing API routes do not, then you should follow existing application convention. ### Controllers & Validation - Always create Form Request classes for validation rather than inline validation in controllers. Include both validation rules and custom error messages. - Check sibling Form Requests to see if the application uses array or string based validation rules. ### Queues - Use queued jobs for time-consuming operations with the `ShouldQueue` interface. ### Authentication & Authorization - Use Laravel's built-in authentication and authorization features (gates, policies, Sanctum, etc.). ### URL Generation - When generating links to other pages, prefer named routes and the `route()` function. ### Configuration - Use environment variables only in configuration files - never use the `env()` function directly outside of config files. Always use `config('app.name')`, not `env('APP_NAME')`. ### Testing - When creating models for tests, use the factories for the models. Check if the factory has custom states that can be used before manually setting up the model. - Faker: Use methods such as `$this->faker->word()` or `fake()->randomDigit()`. Follow existing conventions whether to use `$this->faker` or `fake()`. - When creating tests, make use of `php artisan make:test [options] {name}` to create a feature test, and pass `--unit` to create a unit test. Most tests should be feature tests. ### Vite Error - If you receive an "Illuminate\Foundation\ViteException: Unable to locate file in Vite manifest" error, you can run `npm run build` or ask the user to run `npm run dev` or `composer run dev`. === laravel/v10 rules === ## Laravel 10 - Use the `search-docs` tool to get version-specific documentation. - Middleware typically live in `app/Http/Middleware/` and service providers in `app/Providers/`. - Laravel 10 has a `bootstrap/app.php` file that creates the application instance and binds kernel contracts, but does not use it for application configuration like Laravel 11: - Middleware registration is in `app/Http/Kernel.php` - Exception handling is in `app/Exceptions/Handler.php` - Console commands and schedule registration is in `app/Console/Kernel.php` - Rate limits likely exist in `RouteServiceProvider` or `app/Http/Kernel.php` - When using Eloquent model casts, you must use `protected $casts = [];` and not the `casts()` method. The `casts()` method isn't available on models in Laravel 10. === livewire/core rules === ## Livewire - Use the `search-docs` tool to find exact version-specific documentation for how to write Livewire and Livewire tests. - Use the `php artisan make:livewire [Posts\CreatePost]` Artisan command to create new components. - State should live on the server, with the UI reflecting it. - All Livewire requests hit the Laravel backend; they're like regular HTTP requests. Always validate form data and run authorization checks in Livewire actions. ## Livewire Best Practices - Livewire components require a single root element. - Use `wire:loading` and `wire:dirty` for delightful loading states. - Add `wire:key` in loops: ```blade @foreach ($items as $item)
{{ $item->name }}
@endforeach ``` - Prefer lifecycle hooks like `mount()`, `updatedFoo()` for initialization and reactive side effects: public function mount(User $user) { $this->user = $user; } public function updatedSearch() { $this->resetPage(); } ## Testing Livewire Livewire::test(Counter::class) ->assertSet('count', 0) ->call('increment') ->assertSet('count', 1) ->assertSee(1) ->assertStatus(200); $this->get('/posts/create') ->assertSeeLivewire(CreatePost::class); === livewire/v3 rules === ## Livewire 3 ### Key Changes From Livewire 2 - These things changed in Livewire 3, but may not have been updated in this application. Verify this application's setup to ensure you conform with application conventions. - Use `wire:model.live` for real-time updates, `wire:model` is now deferred by default. - Components now use the `App\Livewire` namespace (not `App\Http\Livewire`). - Use `$this->dispatch()` to dispatch events (not `emit` or `dispatchBrowserEvent`). - Use the `components.layouts.app` view as the typical layout path (not `layouts.app`). ### New Directives - `wire:show`, `wire:transition`, `wire:cloak`, `wire:offline`, `wire:target` are available for use. Use the documentation to find usage examples. ### Alpine - Alpine is now included with Livewire; don't manually include Alpine.js. - Plugins included with Alpine: persist, intersect, collapse, and focus. ### Lifecycle Hooks - You can listen for `livewire:init` to hook into Livewire initialization, and `fail.status === 419` for the page expiring: document.addEventListener('livewire:init', function () { Livewire.hook('request', ({ fail }) => { if (fail && fail.status === 419) { alert('Your session expired'); } }); Livewire.hook('message.failed', (message, component) => { console.error(message); }); }); === phpunit/core rules === ## PHPUnit - This application uses PHPUnit for testing. All tests must be written as PHPUnit classes. Use `php artisan make:test --phpunit {name}` to create a new test. - If you see a test using "Pest", convert it to PHPUnit. - Every time a test has been updated, run that singular test. - When the tests relating to your feature are passing, ask the user if they would like to also run the entire test suite to make sure everything is still passing. - Tests should test all of the happy paths, failure paths, and weird paths. - You must not remove any tests or test files from the tests directory without approval. These are not temporary or helper files; these are core to the application. ### Running Tests - Run the minimal number of tests, using an appropriate filter, before finalizing. - To run all tests: `php artisan test --compact`. - To run all tests in a file: `php artisan test --compact tests/Feature/ExampleTest.php`. - To filter on a particular test name: `php artisan test --compact --filter=testName` (recommended after making a change to a related file).