# Configuration File for AI Coding Assistants (agents.md)

## 1. Contexto del Proyecto

El sistema consiste en una **plataforma web orientada a la conversión** para un corredor de seguros, diseñada bajo un enfoque de **Producto Mínimo Viable (MVP)**. El objetivo principal es la captación estructurada de prospectos (_leads_) interesados en pólizas, centralizando la información para facilitar la gestión comercial del corredor.

### Flujo de Operación del MVP

- **Frontend Público:** Una _Landing Page_ rápida y adaptada a dispositivos móviles. Contiene una sección principal de alta conversión (_Hero_) y una cuadrícula de tarjetas interactiva que clasifica los ramos de seguros (Auto, Salud, Vida, Hogar). Cada tarjeta activa un formulario de contacto dinámico o redirige al enlace de afiliado (_partner_) del corredor.
- **Backend Administrable:** Un panel de control privado (_Backoffice_) desarrollado con **Filament PHP v3** que permite al corredor visualizar, buscar y filtrar los _leads_ entrantes en tiempo real, además de actualizar de forma autónoma los enlaces y nombres de las aseguradoras aliadas.

---

## 2. Arquitectura del Sistema

Para garantizar que el desarrollo en paralelo sea fluido y evitar colisiones de código en Git, implementamos una estructura de **Monolito Modular** simplificado. La lógica de negocio se separa en contextos delimitados dentro del directorio principal de la aplicación.

### Estructura del Directorio del Proyecto

app/
├── Core/ # Infraestructura transversal (Base Models, Traits, Config globales)
└── Modules/ # Contextos Delimitados del Sistema
├── CoreInsurance/ # Motor del negocio de seguros (Modelos: Pólizas, Aseguradoras)
├── Marketing/ # Capa pública (Controladores de la Landing, Livewire, DTOs de leads)
└── Backoffice/ # Panel privado del corredor (Recursos de Filament PHP v3, validaciones)

### Reglas de Dominio Inquebrantables

- **Aislamiento de Módulos:** Los controladores o vistas de la capa de Marketing no deben instanciar directamente modelos exclusivos de la lógica interna de administración. La comunicación entre módulos se realiza mediante servicios públicos o eventos compartidos.
- **Lectura Desacoplada:** El módulo de Marketing consume la configuración de las tarjetas y URLs de partners guardadas por el corredor en modalidad de solo lectura, evitando afectar el rendimiento del backoffice.

## 3. Convenciones de Código y Estilo

Con el fin de unificar el estándar de desarrollo entre los miembros del equipo y mantener el repositorio con un diseño homogéneo y profesional, se establecen las siguientes directrices obligatorias de escritura:

### Reglas Estrictas de Estilo

- **Tipado Fuerte:** Se debe incluir la declaración estricta de tipos al inicio de cada archivo PHP: `declare(strict_types=1);`.
- **Idioma del Código:** Toda la estructura lógica (nombres de variables, funciones, clases, métodos, comentarios técnicos y base de datos) se escribe estrictamente en inglés. El contenido comercial de cara al usuario se maneja en español.
- **Nomenclatura (Naming Conventions):**

| Elemento de Código           | Convención Aplicada     | Ejemplo Técnico                             |
| ---------------------------- | ----------------------- | ------------------------------------------- |
| Clases / Modelos / Providers | StudlyCaps (PascalCase) | `InsuranceLandingController`, `LeadRequest` |
| Variables / Propiedades      | camelCase               | `$insuranceProvider`, `$leadStatus`         |
| Métodos / Funciones          | camelCase               | `createNewLead()`, `getPartnerUrl()`        |
| Tablas / Columnas de DB      | snake_case              | `insurance_categories`, `partner_url`       |

## 4. Consideraciones Técnicas Relevantes

### Frontend Responsivo

La interfaz pública utiliza Tailwind CSS bajo la estrategia Mobile-First. El control del modal interactivo del formulario y los componentes dinámicos de la interfaz (como los acordeones de Preguntas Frecuentes) se delegan exclusivamente a Alpine.js para garantizar una experiencia ligera en el navegador del cliente.

### Validación y Seguridad

Toda petición entrante desde los formularios públicos debe sanitizarse y validarse rigurosamente en el servidor a través de clases FormRequest antes de impactar los modelos de Eloquent. El panel de administración de Filament PHP se resguarda bajo middlewares de autenticación nativos para mitigar vulnerabilidades de acceso y prevenir fugas de información de los prospectos.