XAcademy Challenge: Football API Fullstack

Descripción General

El presente proyecto constituye la solución técnica integral al desafío fullstack. Consiste en una aplicación web diseñada para la gestión, visualización y administración de perfiles de jugadores de fútbol, soportada por un backend en NestJS, una base de datos MySQL inicializada de manera automatizada y una interfaz de usuario desarrollada en Angular. Todo el entorno se encuentra orquestado y empaquetado bajo tecnología Docker.

Arquitectura y Componentes

El sistema se ha diseñado bajo una estricta separación de responsabilidades funcionales y de infraestructura:

• Frontend (Angular): Aplicación web responsiva de una sola página (SPA). Construida utilizando componentes reactivos, ruteo protegido y comunicación por servicios HTTP que inyectan el token JWT globalmente mediante interceptores.
• Backend (NestJS): Interfaz de Programación de Aplicaciones (API) de naturaleza REST. Su diseño estructural implementa el Patrón Repository (para el desacoplamiento en el acceso a datos) e Inyección de Dependencias. Se proveen controladores blindados por autenticación (Guards) y DTOs para la validación estricta en el tráfico de entrada.
• Base de Datos (MySQL): Capa de persistencia enlazada vía el ORM Sequelize. Inicializa su esquema base poblado con registros a través de un archivo SQL (init.sql), permitiendo paralelamente la generación estructurada y sincronizada de nuevas entidades como usuarios.

Requisitos Previos

La arquitectura se estructuró bajo el principio de portabilidad absoluta mediante contenedores. Para el despliegue del ecosistema de desarrollo o producción, no se requiere la instalación de Node.js, Angular CLI ni motores de bases de datos locales.

Requisitos estrictos de infraestructura host:

• Docker Engine
• Docker Compose

Guía de Despliegue Paso a Paso (Walkthrough)

1. Clonar el repositorio Ejecutar la clonación del repositorio hacia el entorno local.

2. Creación del entorno En la raíz del proyecto, crear el archivo que gobernará la configuración de contenedores copiando la plantilla provista:

   cp .env.example .env

3. Construcción y ejecución Ejecutar el comando unificado que se encarga de crear la red, levantar el motor de base de datos e instruir el aislamiento y construcción interna de las dependencias tanto para el Backend como el Frontend:

   docker-compose up --build

4. Direcciones de acceso local Una vez que el orquestador finalice de estabilizar los servicios, los recursos quedan expuestos en los siguientes puertos:

   • Frontend (Angular): http://localhost:4200
   • Backend API (NestJS): http://localhost:3000
   • Interfaz de documentación OpenAPI (Swagger): http://localhost:3000/api/docs

Decisiones Críticas de Diseño e Ingeniería

Durante la integración del ORM Sequelize con la base de datos MySQL provista mediante el archivo de volcado inicial, se detectó una inestabilidad técnica vinculada al controlador nativo mysql2. Dicho driver presentaba problemas de codificación e ignoraba las directivas globales, inyectando ruido de caracteres bajo formato Latin1 que afectaba las consultas no directas y la persistencia de atributos específicos.

Se optó por una solución pragmática de blindaje de datos a nivel de capa de aplicación, garantizando estabilidad sin corromper la base de datos de origen ni deshabilitar el flag synchronize: true (necesario para el ecosistema de autenticación de usuarios):

• Blindaje en Modelo (PlayerModel): Se aplicaron interceptores de lectura y escritura (getters y setters) en las columnas críticas. Las mutaciones convierten el flujo a la codificación requerida en tiempo real, contrarrestando la deficiencia de transporte del driver en inserciones directas (POST/PATCH) y lecturas primarias.
• Blindaje en Servicios (PlayersService): Se desarrolló el helper de pre-procesamiento fixFilterEncoding. Este método intercepta y sanitiza las búsquedas de los filtros activos del DTO antes de su delegación a las consultas de Sequelize, aislando el Patrón Repository de las correcciones de codificación derivadas del controlador.

Gestión de Datos Masivos: Importación Transaccional de CSV

Para la carga masiva de perfiles de jugadores desde archivos externos, se diseñó un flujo robusto en el backend (PlayersService) que mitiga el riesgo de corrupción de datos y colisiones de IDs:

• Estrategia Transaccional de Base de Datos: El procesamiento del archivo CSV se ejecuta bajo una transacción unificada de Sequelize. Si una sola línea del archivo falla en sus validaciones o contiene tipos de datos corruptos, el sistema realiza un rollback automático, garantizando la atomicidad de la operación (todo o nada).
• Resolución de Conflictos de Identidad (Upsert): En lugar de fallar ante registros duplicados, el algoritmo implementa una lógica de combinación inteligente (upsert). Si el jugador ya existe en la base de datos basándose en claves únicas, sus atributos estadísticos se actualizan con los nuevos valores del CSV; de lo contrario, se crea un nuevo registro sin romper la secuencia de autoincrementales.

Integración de Inteligencia Artificial Local y Control de Infraestructura (Ollama)

Se integró un modelo de lenguaje (LLM) directamente en el ciclo de vida de los contenedores Docker para dotar a la plataforma de análisis predictivos año a año, resolviendo severas restricciones de hardware y privacidad:

• Mitigación de Desbordamiento de Memoria (OOM): Se seleccionó estratégicamente el modelo liviano qwen2.5:0.5b (350 MB) ejecutado localmente a través de Ollama. Esto garantiza la portabilidad absoluta del challenge en cualquier computadora común basada en CPU, evitando colapsos de memoria RAM sin depender de costosas APIs en la nube o placas de video (GPU) dedicadas.
• Ciclo de Vida e Instalación Dinámica Interactiva: El backend de NestJS expone endpoints de control (/api/tags y /api/pull) consumidos reactivamente por el frontend en Angular. Esto permite al usuario verificar en tiempo real si el modelo está instalado y disparar la descarga de la red neuronal directamente desde la interfaz web, sin requerir comandos manuales en la consola del sistema host.
• Robustez en Inferencia Bajo CPU (Persistent Connections): Dado que el procesamiento del timeline estadístico completo bajo CPU demanda un alto tiempo de cómputo, se configuró un AbortSignal.timeout(600000) (10 minutos) en la llamada nativa de fetch dentro de IaService. Esto evita el error de corte prematuro UND_ERR_HEADERS_TIMEOUT de la librería Undici de Node.js, manteniendo la cañería síncrona abierta hasta finalizar el reporte.
• Anonimización Dinámica contra Falsos Positivos de Censura: Para evadir los filtros rígidos de privacidad del modelo base ante nombres de celebridades reales (como Lionel Messi), el backend abstrae y anonimiza los datos a un perfil genérico ("Jugador de campo profesional") antes de enviarlo al prompt. Una vez obtenido el dictamen matemático puro, el servicio reinyecta dinámicamente el nombre real del jugador mediante manipulación de strings antes de enviarlo al frontend.

Estado de Funcionalidades

El ecosistema cuenta con los siguientes requerimientos completados y en estado operativo:

• Grilla paginada controlada de manera transaccional desde el servidor.
• Filtros combinados por campos activos del DTO.
• Interfaz gráfica detallada con integraciones visuales de atributos estadísticos.
• Formulario reactivo de edición persistente y creación con validaciones condicionales.
• Exportación transaccional a formato CSV incorporando la codificación BOM \uFEFF.
• Autenticación asimétrica basada en JSON Web Tokens y protección en capas (Guards y Roles).
• Especificación técnica generada en tiempo real mediante Swagger (OpenAPI).
• Importación masiva y transaccional de jugadores mediante archivos CSV con procesamiento de headers y rollback ante fallas de validación.
• Diagnóstico predictivo de jugadores mediante un motor de IA local aislado (qwen2.5:0.5b), orquestado dinámicamente desde el Frontend (Angular) hacia el Backend (NestJS + Ollama).