🧪 Quizzes Profe Nacho
Plataforma web full-stack de quizzes educativos interactivos. Los estudiantes practican jugando y el docente administra el contenido, hace seguimiento de resultados y comparte los quizzes con un enlace o un código QR.
El problema que resuelve
Como docente de ciencias naturales necesitaba una forma ágil de que mis estudiantes practicaran y afianzaran conceptos, y de tener un registro real de cómo les iba. Las herramientas que probé eran caras, no permitían usar imágenes en las preguntas (algo clave para química y biología, donde hay que reconocer estructuras, moléculas o esquemas) o no dejaban hacer seguimiento por curso.
Así que la construí. Quizzes Profe Nacho está pensada desde el aula real: un docente carga sus propios quizzes con imágenes, los comparte con un QR impreso en el pizarrón o pegado en la carpeta, y los estudiantes juegan desde el celular. El docente después ve los promedios agrupados por escuela, año y división.
Hoy la uso con contenidos de mis propios proyectos áulicos, como el sistema de riego automatizado BioSolar y la unidad de biología de los alimentos.
Demo en vivo
App: https://quizzes-profe-nacho.vercel.app/
Los quizzes son públicos y se puede entrar sin cuenta para probarlos. El registro es opcional y sirve para que a los estudiantes se les guarden los resultados.
Funcionalidades
Para estudiantes
- Acceso a los quizzes de su curso por enlace directo o código QR.
- Un solo intento por quiz, controlado en el servidor. Si se corta internet, retoma donde quedó.
- Registro eligiendo modalidad, escuela y curso de listas que arma el docente (sin escribir a mano). La cuenta queda pendiente hasta que el docente la aprueba, y la pantalla de espera se actualiza sola.
- Preguntas y opciones con imágenes, y explicación al responder cada una.
- Temporizador configurable por pregunta (5, 10, 15, 20, 30 segundos o sin límite).
- Nota final en escala de 0 a 10 (solo cuentan las respuestas correctas) y puntos con bonus por rapidez para el ranking.
- Modo sin cuenta para los quizzes que el docente abre al público (ferias de ciencia), sin guardar resultados.
- Historial de resultados y promedios para quienes tienen cuenta.
- Interfaz responsive y modo oscuro automático.
Para el administrador (docente)
- Panel de administración protegido con contraseña.
- Alta, edición y baja de quizzes, organizados en secciones o rondas.
- Carga de preguntas con imágenes en el enunciado y en cada opción, incluida la edición de esas imágenes.
- Configuración del tiempo por pregunta.
- Generación y descarga del código QR de cada quiz en PDF, listo para imprimir.
- Alta, edición, ocultamiento y baja de modalidades, escuelas y cursos.
- Panel de seguimiento por curso, con el promedio general y el de cada quiz en escala 0 a 10.
- Asignación de alumnos a su curso (útil para corregir registros viejos), sin perder sus notas.
- Habilitación de cada quiz por curso, y opción de abrirlo sin cuenta.
- Ficha de cada alumno con nota, puntos, fecha y duración de cada quiz, con búsqueda por nombre, escuela y curso.
- Habilitar otro intento (cuenta la mejor nota) o borrar la nota de un alumno en un quiz.
- Aprobación de alumnos nuevos (de a uno, corrigiendo el nombre, o todo un curso junto), con el número de pendientes a la vista en el panel. Cambio de nombre y bloqueo desde la ficha.
- Edición manual de la nota de un quiz, con registro de la nota original, la fecha y quién la cambió.
- Recálculo de las notas de un quiz ya jugado cuando se corrige la respuesta correcta de una pregunta, con vista previa antes de aplicar.
- Ranking en vivo para proyectar en el aula, que se actualiza cada 3 segundos, con podio y confeti al terminar.
Stack tecnológico
| Área | Tecnología |
|---|
| Framework | Next.js 16 (React 19, App Router) |
| Lenguaje | TypeScript |
| Base de datos | SQLite en Turso |
| ORM | Drizzle |
| Almacenamiento de imágenes | Vercel Blob |
| Estilos | Tailwind CSS |
| Hash de contraseñas | bcryptjs |
| Testing | Vitest |
| Generación de QR y PDF | qrcode.react + jsPDF |
| Deploy | Vercel (despliegue continuo desde GitHub) |
Aspectos técnicos destacados
- Base de datos relacional con Drizzle ORM sobre Turso, modelando quizzes, secciones, preguntas, opciones, usuarios y resultados, con consultas tipadas de punta a punta.
- Contraseñas hasheadas con bcryptjs, nunca guardadas en texto plano.
- Carga y gestión de imágenes en preguntas y opciones usando Vercel Blob, incluida la sustitución de imágenes al editar.
- Generación de códigos QR descargables en PDF con qrcode.react y jsPDF, para llevar los quizzes del entorno digital al aula física.
- Autenticación con distintas modalidades de usuario y panel de administración protegido.
- Tiempo medido en el servidor: el navegador del alumno nunca recibe la respuesta correcta antes de responder, y el servidor decide si llegó a tiempo.
- Pruebas con Vitest sobre el cálculo de notas y puntos, la regla de un intento, habilitar y borrar intentos, el ranking y su podio, la aprobación de alumnos, las notas editadas y el recálculo, contra una base de prueba armada con los mismos scripts SQL que producción.
Ejecutar localmente
Requisitos: Node.js 20 o superior y una cuenta de Turso.
# 1. Clonar el repositorio
git clone https://github.com/garciahernan25-ui/quizzes-profe-nacho.git
cd quizzes-profe-nacho
# 2. Instalar dependencias
npm install
# 3. Crear el archivo .env.local con las variables de abajo
# 4. Aplicar el esquema a una base de datos NUEVA (vacía)
npx drizzle-kit push
# 5. Levantar el servidor de desarrollo
npm run dev
La app queda corriendo en http://localhost:3000.
Cambios en la base de producción
No usar drizzle-kit push sobre la base de producción. Los cambios se escriben como SQL en scripts/sql/ y se aplican así:
# 1. Respaldo (solo lectura; queda en /backups, que no se sube a git)
npx dotenv -e .env.local -- npx tsx scripts/respaldo.ts
# 2. Ver qué se va a aplicar (no toca nada)
npx dotenv -e .env.local -- npx tsx scripts/aplicar-sql.ts scripts/sql/ARCHIVO.sql
# 3. Aplicar (todo junto, o nada si algo falla)
npx dotenv -e .env.local -- npx tsx scripts/aplicar-sql.ts scripts/sql/ARCHIVO.sql --confirmar
Variables de entorno
Creá un archivo .env.local en la raíz con estas variables:
TURSO_DATABASE_URL=
TURSO_AUTH_TOKEN=
BLOB_READ_WRITE_TOKEN=
ADMIN_PASSWORD=
AUTH_SECRET=
# Opcional: token compartido con la Agenda docente (mínimo 32 caracteres)
AGENDA_TOKEN=
Con AGENDA_TOKEN configurado, la Agenda docente puede leer las notas de los quizzes desde GET /api/agenda/notas (encabezado Authorization: Bearer <token>). Es solo lectura y devuelve la misma nota que muestra el seguimiento.
Tests
npm test
Los tests usan una base temporal propia: no necesitan .env.local ni tocan la base real.
Autor
Hernán Andrés García
GitHub
