# Arquitectura de Yupana

El documento de arquitectura de Yupana, con las doce secciones de arc42. Es un
esquema: cada sección tiene lo que alguien del equipo o de la facultad ya
vino a preguntar, y enlaza los archivos donde vive el detalle en vez de
copiarlos.

## 1. Introducción y objetivos

Yupana es el juez de tareas de programación de la facultad: recibe la solución
de un estudiante, la ejecuta contra casos de prueba ocultos y publica un
veredicto. Lo usan 6 cursos.

Objetivos de calidad, en orden:

1. El veredicto llega mientras el estudiante todavía trabaja en la tarea,
   también la noche del cierre (E1).
2. El programa de un estudiante no puede leer nada que no sea suyo ni afectar
   a los demás (E2).
3. Ningún envío confirmado se pierde (E3).

| Stakeholder | Qué espera |
|---|---|
| Estudiantes | Veredicto pronto y el mismo trato para todos |
| Docentes | Publicar una tarea sin ayuda, y confiar en los veredictos |
| Jefes de práctica (el equipo) | Poder operarlo dos personas a tiempo parcial |
| Administración de servidores de la facultad | Que no comprometa la máquina ni la red de la facultad |

## 2. Restricciones

- Corre en una máquina virtual de la facultad, con 4 núcleos. No hay
  presupuesto para servicios en la nube.
- El inicio de sesión es el de la universidad (OpenID Connect): Yupana no
  guarda contraseñas.
- La facultad respalda solo la base de datos, cada noche.
- Node.js y PostgreSQL, que es lo que el equipo conoce.

## 3. Contexto y alcance

El diagrama de contexto: [`c4/context.md`](c4/context.md). Yupana no decide
quién está matriculado (lo dice el sistema de matrícula) ni registra las
notas del curso: entrega veredictos, y cada docente decide qué hace con ellos.

## 4. Estrategia de solución

- Recibir y calificar son procesos distintos, unidos por una tabla de
  trabajos en PostgreSQL (ADR 0003): atiende E1 sin agregar infraestructura.
- Todo código de estudiantes corre dentro de un sandbox sin red y con
  límites, en los workers y nunca en la API: atiende E2.
- El envío y su código se guardan en una transacción antes de confirmar
  (ADR 0002): atiende E3.

## 5. Vista de bloques

- Nivel 1, los contenedores: [`c4/containers.md`](c4/containers.md).
- Nivel 2, los componentes de la API: [`c4/components.md`](c4/components.md).
- El worker de calificación todavía no tiene su diagrama de componentes: son
  tres archivos, y se leen más rápido que un diagrama.

## 6. Vista de ejecución

Un envío, desde que el estudiante lo manda hasta que ve el veredicto:

1. La aplicación web manda el archivo a la API (HTTPS).
2. *HTTP* le pregunta a *Sesiones* quién es, y le entrega el envío a *Envíos*.
3. *Envíos* comprueba con *Cursos*, *Tareas* y *Lenguajes* que la persona
   está matriculada, la tarea sigue abierta y el lenguaje está aceptado.
4. *Envíos* guarda el envío, su código y un trabajo pendiente en una
   transacción. La API responde 202 con el identificador del envío.
5. Un worker, en su consulta de cada 2 s, toma el trabajo y lo marca "en
   calificación".
6. El worker compila el código y lo ejecuta contra cada caso de prueba dentro
   de un sandbox, y anota el veredicto.
7. La aplicación web, que pregunta cada 3 s, recibe el veredicto de
   *Veredictos* y lo muestra.

Falta escribir el recorrido de un worker que muere en el paso 6: hoy no está
decidido (ver la sección 11).

## 7. Vista de despliegue

Una máquina virtual de la facultad, con 4 núcleos y Linux. En ella corren la
API (un proceso), 2 workers de calificación, PostgreSQL y el cron de la
sincronización de matrícula. La carpeta de casos de prueba está en el disco
de la misma máquina. Delante hay un proxy de la facultad que termina HTTPS.

## 8. Conceptos transversales

- Sesiones: después del inicio de sesión con la universidad, Yupana emite su
  propia cookie firmada, válida por 8 horas.
- Errores de la API: siempre `{ "error": { "code", "message" } }`.
- Estados de un envío: pendiente, en calificación, y un veredicto final
  (aceptado, respuesta incorrecta, tiempo excedido, error de compilación,
  error en ejecución). Solo los workers cambian el estado.
- Horas: en UTC en la base de datos; el cierre de una tarea se compara con el
  reloj de la base de datos, no con el del navegador.

## 9. Decisiones de arquitectura

| ADR | Decisión | Estado |
|---|---|---|
| [0001](adr/0001-calificar-dentro-del-pedido-http.md) | Calificar cada envío dentro del pedido HTTP | Reemplazado por el ADR 0003 |
| [0002](adr/0002-guardar-el-codigo-de-los-envios-en-postgresql.md) | Guardar el código de los envíos en PostgreSQL | Aceptado |
| [0003](adr/0003-tabla-de-trabajos-y-workers-de-calificacion.md) | Calificar fuera de la API, con una tabla de trabajos y workers | Aceptado |

## 10. Requisitos de calidad

El utility tree está en [`utility-tree.md`](utility-tree.md) y los escenarios
completos en [`scenarios.md`](scenarios.md).

## 11. Riesgos y deuda técnica

Los riesgos de la última evaluación están en [`atam.md`](atam.md). Los dos
temas: la tabla de trabajos no tiene reglas de cola (capacidad, trabajos
abandonados, prioridades), y los workers tienen más acceso del que necesitan.
Deuda conocida: no hay política para archivar los envíos de semestres pasados
(ADR 0002).

## 12. Glosario

| Término | Significado |
|---|---|
| Envío | Un archivo de código que un estudiante manda como solución de una tarea |
| Caso de prueba | Un archivo de entrada y su salida esperada |
| Veredicto | El resultado de calificar un envío: aceptado, respuesta incorrecta, tiempo excedido, error de compilación o error en ejecución |
| Cierre | El momento desde el cual una tarea ya no acepta envíos |
| Trabajo | La fila que dice que un envío está pendiente de calificar |
| Sandbox | El entorno aislado en el que se ejecuta el programa de un estudiante |
