De un Sistema de Gamificación a Batallas 1v1: Modernizando Moodle con React y Arquitectura Hexagonal

El Origen del Desafío

Al diseñar una solución de gamificación para un campus virtual en producción, el objetivo inicial era claro y medible: permitir que el alumno, al finalizar un cuestionario, conociera su posición relativa frente al resto, su promedio histórico y pudiera acumular puntos por constancia (como ingresar más de tres días consecutivos o superar determinados puntajes).

Durante esa etapa de definición técnica surgió la pregunta que amplió radicalmente el alcance del proyecto: “¿Es posible incorporar además un sistema de batallas donde un estudiante pueda retar directamente a otro?”.

Se asumió el reto. La premisa técnica fue estricta desde el inicio: el módulo de duelos debía operar de forma completamente independiente de la gamificación general de Moodle, contando con sus propias reglas de negocio, su propio sistema de puntuación y un ranking autónomo. Además, el servicio debía funcionar como una solución llave en mano: la plataforma no debía asumir la carga operativa de redactar ni configurar preguntas especiales; la dinámica debía entregarse completamente resuelta e integrada al flujo natural de estudio.

El mayor riesgo en estos desarrollos es la fricción. Forzar al estudiante a crearse otra cuenta, abrir pestañas adicionales o interactuar con servicios externos destruye el hábito de uso. La experiencia debía vivir dentro de Moodle mediante una interfaz en React moderna, rápida y encapsulada en un modal accesible desde la barra superior, la pantalla de inicio o al concluir una lección.

Arquitectura, Seguridad y Resolución de Casos Borde

Montar dinámicas interactivas sobre un LMS con dos décadas de historia técnica exige límites arquitectónicos estrictos para no comprometer la estabilidad del servidor ni permitir inconsistencias en los datos.

Arquitectura Hexagonal y Aislamiento del Dominio

Para asegurar que el módulo fuera independiente y mantenible, construimos el plugin local_tipddy_duel bajo Arquitectura Hexagonal en PHP:

• Dominio Puro (classes/local/service/): Toda la lógica (crear un reto, responder, calcular resultados y verificar expiración) se implementó en clases desacopladas de las funciones globales de Moodle y de la base de datos.
• Adaptadores Externos (classes/external/): Controladores que reciben las peticiones de los WebServices de Moodle, aplican tipado estricto (PARAM_INT, PARAM_ALPHANUM), validan permisos y traducen las excepciones del dominio a \moodle_exception estructuradas.
• Autenticación sin credenciales expuestas: La SPA en React consume las APIs mediante el token de sesión institucional del usuario (wstoken). Un contexto en React (AuthContext) y el hook useValidToken gestionan la validez de la sesión en segundo plano sin almacenar contraseñas en el navegador.

Los Casos Borde: Diseñar para el Mundo Real

Donde realmente se pone a prueba la arquitectura de un juego es en los imprevistos de red y comportamiento de los usuarios:

1. ¿Qué pasa si un alumno se desconecta a mitad de la partida?Descartamos almacenar el estado en el cliente para enviarlo todo al final. Cada respuesta se persiste y califica de manera atómica e inmediata en el servidor (challenge_repository.php). Si un jugador pierde conexión en la pregunta 3 de 5, las dos anteriores quedan registradas. El duelo no se corrompe y puede reanudarse o cerrarse limpiamente sin perder datos.
2. ¿Qué pasa si alguien se demora o abandona una pregunta?Cada pregunta corre con un temporizador estricto por turno. Si el tiempo expira sin acción, la pregunta se contabiliza automáticamente como incorrecta y el flujo avanza. Si el rival no responde el desafío completo dentro del plazo configurado, el duelo expira de forma automática.
3. ¿Cómo se resuelve un empate en respuestas correctas?El sistema no sortea ni declara empates triviales. Implementamos un criterio de desempate por velocidad: si ambos participantes aciertan 4 de 5 preguntas, el ganador se define por la suma exacta de milisegundos empleados en responder.
4. ¿Cómo se evitan trampas e inspección de código? (Filosofía Zero-Trust)Por definición arquitectónica (ADR-0002), el cliente React nunca recibe las respuestas correctas ni calcula puntajes. Todo el cálculo ocurre en el servidor. La máquina de estados (useBattleStateMachine.js) delega cada validación al backend. Si la red falla, la UI muestra un estado de error con reintento, sin fabricar jamás resultados ficticios.
5. Observabilidad sin acceso SSH (El reto del entorno corporativo)En servidores de producción donde no se dispone de acceso a consola ni a logs del sistema, implementamos un subsistema de telemetría interno con feature flag activable desde la administración de Moodle. Esto permite auditar errores de red, fallos de tokens y excepciones de base de datos directamente desde la interfaz gráfica sin degradar el rendimiento.

Rendimiento y Retorno de Inversión

Eliminando el Cuello de Botella N+1

En las primeras pruebas, iniciar una batalla exigía encadenar múltiples llamadas REST a Moodle: verificar usuario, consultar el curso, traer preguntas y crear el intento. Con decenas de alumnos simultáneos, esto multiplicaba las consultas SQL y generaba lentitud perceptible.

Lo resolvimos creando un endpoint compuesto en local_tipddy_duel:

• En un solo viaje HTTP de milisegundos, el servidor entrega el estado del duelo, las 5 preguntas seleccionadas al azar con alternativas ya barajadas y los datos del oponente.
• La app React vive montada en memoria: el modal abre con 0 ms de recarga de página.
• Las consultas de oponentes y rankings aplican paginación nativa SQL (LIMIT y OFFSET), evitando saturar la memoria RAM del servidor.

¿Por qué esta solución y no un SaaS externo o un plugin genérico?

Conclusión

El desarrollo de tipddy_duel demostró que no hace falta descartar un LMS robusto como Moodle para ofrecer una experiencia contemporánea y atractiva. La clave estuvo en abordar el desafío técnico sin atajos: delimitando el dominio con Arquitectura Hexagonal, diseñando para los casos borde reales y desacoplando la interfaz con React para que el aprendizaje vuelva a ser una experiencia activa y compartida.