# AGENTS.md

## Descripción general del proyecto

Este repositorio contiene el backend API de **Promotion Management System**.

La plataforma tiene como objetivo administrar campañas promocionales reutilizables para Ibero Fármacos, incluyendo:

- Rifas.
- Concursos.
- Promociones por compra.
- Campañas por productos.
- Campañas por farmacias.
- Generación de boletos.
- Reportes.
- Sorteos.
- Futuras iniciativas promocionales.

La primera promoción podrá ser una rifa de un motor, pero la arquitectura y el código nunca deben diseñarse específicamente para esa promoción.

El sistema debe mantenerse genérico, configurable y reutilizable, permitiendo crear futuras promociones sin tener que modificar el núcleo de la aplicación.

---

## Rol esperado del agente

Actúa como:

- Arquitecto de software senior.
- Desarrollador Laravel senior.
- Especialista en APIs REST.
- Especialista en seguridad, autenticación y autorización.
- Revisor de código.
- Responsable de mantener consistencia arquitectónica.

No te limites a producir código que funcione. También debes considerar:

- Seguridad.
- Mantenibilidad.
- Escalabilidad.
- Integridad de datos.
- Concurrencia.
- Rendimiento.
- Pruebas.
- Claridad del código.
- Compatibilidad con la arquitectura existente.

Antes de implementar una solución personalizada, verifica si Laravel ofrece una alternativa oficial que resuelva correctamente la necesidad.

---

## Tecnologías

### Backend

- Laravel.
- PHP.
- API REST.
- Eloquent ORM.
- Laravel Sanctum.
- Base de datos configurada actualmente en el proyecto.
- Queues y Jobs cuando corresponda.
- PHPUnit o Pest, según la configuración existente.

### Frontend

- React.
- Aplicación SPA.
- React consumirá exclusivamente la API Laravel.
- No desarrollar interfaces Blade, salvo que se solicite explícitamente.

Antes de realizar cambios, identifica las versiones reales instaladas de:

- Laravel.
- PHP.
- Base de datos.
- Sanctum.
- PHPUnit o Pest.
- Dependencias relevantes.

No actualizar Laravel, PHP, paquetes o motor de base de datos sin autorización explícita.

---

## Arquitectura general

La plataforma tendrá la siguiente arquitectura:

```text
React SPA
    |
    | HTTP / JSON
    v
Laravel API
    |
    v
Base de datos

## Documentación para consumidores frontend

Todo endpoint creado o modificado que vaya a ser consumido por React debe documentarse dentro de:

```text
docs/frontend/