ADR-002: Stack de Backend — Laravel 13 + PHP 8.5

Date: 2026-07-25 Status: Accepted

Corrección

En la primera pasada de este plan, el Product Owner armó un backend en Node.js/Express por default, sin haber confirmado el lenguaje con el cliente. Esto fue un error: el cliente ya tiene un proyecto existente con la API de Soterex implementada en PHP Laravel (que va a compartir más adelante), y ese es el stack que corresponde para mantener consistencia entre proyectos y poder eventualmente reutilizar/integrar código entre ambos.

Decision

Backend en Laravel 13 (última versión estable, marzo 2026) sobre PHP 8.5 (última versión estable de PHP a julio 2026; Laravel 13 solo exige PHP 8.3+ como mínimo, pero se usa la última por pedido explícito del cliente de ir con "todo lo más nuevo").

Piezas del stack:

• Auth: kreait/laravel-firebase para validar en el backend el ID token JWT que emite Firebase Auth del lado del frontend (mismo patrón que ya usa el portal de documentación).
• Base de datos: PostgreSQL (driver pgsql) — ver ADR-003 para el detalle de por qué, y por qué Aurora en vez de RDS estándar.
• Cache + Colas: Redis. Los jobs (ingesta de SendRequest cada 30 min, notificaciones a Soterex) se encolan en vez de ejecutarse de forma síncrona — mejor performance y reintentos automáticos ante fallas transitorias, en vez de que un timeout de Soterex bloquee un request HTTP o una corrida del scheduler.
• Scheduler: routes/console.php con Schedule::job(...)->everyThirtyMinutes() (sintaxis moderna de Laravel 11+, sin App\Console\Kernel).
• ORM: Eloquent, con UUIDs como primary key en todas las tablas (HasUuids), consistente con el uso de UUID en el resto del sistema (Firebase UIDs, MTCN como string, etc.).

Rationale

• Mantener el mismo lenguaje/framework que el proyecto de Soterex existente reduce fricción para reutilizar lógica de integración (el SoterexClient de este proyecto está escrito para que sea fácil de alinear o reemplazar cuando se comparta ese código).
• Laravel trae de fábrica lo que este proyecto necesita sin ensamblar librerías sueltas: scheduler, colas, migraciones, Eloquent, validación, políticas de autorización — encaja bien con la necesidad de una matriz de permisos (L/E/B) y ABMs (Países, Estaciones, Usuarios, Roles).

Alternatives Considered

• Node.js/Express (descartado — decisión inicial incorrecta, revertida en esta ADR).

Consequences

• Positivo: consistencia con el ecosistema existente del cliente; Laravel Policies son un buen fit natural para la matriz de permisos configurable (sección 2 del Análisis Funcional).
• Negativo: ninguno relevante — es la opción correcta para este cliente.
• Nota técnica: el composer.json/estructura de este repo se escribieron a mano en el entorno de generación de este plan porque no había acceso de red a Packagist para correr composer create-project — correr composer install en un entorno con internet normal (Docker build, CI) resuelve esto sin cambios de código.

Next Steps

• Cuando el cliente comparta el proyecto Laravel existente de Soterex, revisar si conviene reusar su SoterexClient/paquete de integración en vez del que se armó acá desde cero.
• backend-dev completa los endpoints reales (hoy son placeholders) según el PRD de cada módulo.