Documentación técnica de SPARK

SPARK (Structured Pedagogical Archive for Reuse of Knowledge) es una aplicación web donde el profesorado y el personal educativo de la University of Twente y de las universidades 4TU comparten, encuentran y reutilizan innovaciones educativas. Se desarrolla dentro del proyecto NPULS, en el paquete de trabajo WP-F.

Esta documentación explica cómo está hecho SPARK por dentro. Está pensada para cualquier persona que vaya a leer, mantener o ampliar el código: tu yo del futuro, un compañero que se incorpora o quien herede el proyecto cuando NPULS termine. No hace falta haber escrito el código para entenderla.

Qué no está aquí (todavía)

La guía para usuarios (cómo buscar o compartir una innovación) y para administradores (cómo gestionar usuarios y contenidos) llegará cuando el software esté terminado. También las traducciones al inglés y al neerlandés.

SPARK en una imagen

• La web (carpeta src/) es lo que ve la persona: páginas, formularios, buscador. Está escrita en React y TypeScript.
• La API (carpeta backend/) es quien decide: comprueba quién eres, valida los datos y lee o escribe en la base de datos. Está escrita en Python con FastAPI.
• La base de datos es PostgreSQL, alojada en Neon (Frankfurt).
• Todo se publica en Vercel: cada vez que el código llega a la rama main de GitHub, la web pública se actualiza sola.

Por dónde empezar

Si quieres…	Lee
Arrancar SPARK en tu ordenador	Instalación local
Entender cómo encajan las piezas	Visión general de la arquitectura
Saber qué hace un archivo concreto	Estructura del repositorio
Ver todos los endpoints de la API	Referencia de la API
Entender las tablas de la base de datos	Modelo de datos
Saber cómo se protegen las cuentas	Seguridad
Hacer un cambio habitual paso a paso	Guías prácticas
Saber por qué algo se hizo así	Registro de decisiones
Entender una sigla (UC-M2, DEV-4, WP-F…)	Glosario
Saber qué está simulado o pendiente	Estado actual y pendientes

Convenciones de esta documentación

• Rutas de archivos como backend/auth.py son relativas a la raíz del repositorio yeruqui/spark.
• El código y sus comentarios están en inglés; esta documentación, en español. Los nombres de funciones, tablas y campos se citan tal cual aparecen en el código.
• Los códigos como UC-C1 o DEV-4 vienen del plan de trabajo de WP-F y se explican en el glosario.
• Cada página tiene un enlace "Editar esta página" al final. La documentación vive en el mismo repositorio que el código (carpeta website/), así que se actualiza en el mismo pull request que el cambio que describe. Ver Mantener esta documentación.