Arquitectura de SIVA

1. Visión general

SIVA es un monolito en dos aplicaciones (backend API + frontend SPA) que se comunican por HTTP/JSON bajo el prefijo /api. La persistencia es SQLite mediante el driver sql.js de TypeORM, con el fichero en backend/data/siva.db.

• Backend: API REST sin estado (stateless) con autenticación JWT. Organizado por capas: routes → middlewares → controllers → services → repositorios TypeORM → BD.
• Frontend: SPA Vue 3 que consume la API mediante una única instancia Axios (src/utils/api.ts). No existe capa services/: los stores Pinia encapsulan las llamadas HTTP.

Diagrama de alto nivel (C4 — contexto y contenedores)

Componentes desplegables

Componente	Tecnología	Puerto	Responsabilidad
frontend	Vue 3 + nginx (prod)	5173 dev / 80 prod	SPA y reverse proxy de /api
backend	Node + Express	3000	API REST, jobs cron, generación de documentos
mailpit	Mailpit	1025 / 8025	Captura de correo en desarrollo/producción de demo
doc-user	VitePress	8080	Manual de usuario publicado
doc-system	VitePress	8081	Documentación de sistema publicada

2. Estructura de carpetas

Responsabilidad por carpeta

Carpeta	Responsabilidad
backend/src/routes/	Declaración de endpoints, montaje de middlewares y binding de controladores.
backend/src/controllers/	Adaptación HTTP: leen req, llaman al servicio y responden con successResponse.
backend/src/services/	Lógica de negocio y acceso a datos vía repositorios TypeORM.
backend/src/entities/	Modelo de datos TypeORM (31 entidades).
backend/src/dtos/	Esquemas de validación Zod de body/query.
backend/src/middlewares/	Autenticación (currentUser/requireAuth), roles, validación, errores, archivos.
backend/src/config/	Entorno, BD, logger, mail, storage, multer, rate limit, Swagger.
backend/src/jobs/	Tareas node-cron horarias.
backend/src/migrations/	Esquema + datos iniciales y de demo.
frontend/src/pages/	Vistas por módulo (auth y dashboard).
frontend/src/components/	Componentes por dominio (base/, layout/, shared/ y <módulo>/modals/).
frontend/src/stores/	Estado global Pinia y acceso a la API.
frontend/src/auth/	Catálogo de permisos y matriz rol→permisos.
frontend/src/types/	Interfaces TypeScript del dominio.
frontend/src/utils/	Axios (api.ts), CSV, fechas, colores, assets, etc.
docs/	Documentación técnica interna (esta carpeta).
documentation/	Sitios VitePress publicados (usuario y sistema).

3. Flujo de datos

El formato de respuesta es homogéneo (backend/src/utils/api-response.ts):

{ "success": true, "data": { } }

{ "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Error de validación", "details": [] } }

4. Flujos de secuencia principales

4.1 Login y refresco de token

4.2 Creación y configuración de un ejercicio

4.3 Llamamiento, confirmación y asignación automática

5. Decisiones de diseño relevantes

Decisión	Justificación (inferida del código)
SQLite (sql.js) con persistencia a fichero	Despliegue autónomo (servidor único y versión pendrive) sin servidor de BD externo. synchronize:false + migraciones garantizan el esquema.
**Respuestas envueltas en `{ success, data	error }`**
JWT con refresh rotativo y refresh_token en BD	Permite invalidar sesiones (logout) y validar el refresh contra el valor almacenado. El interceptor de Axios refresca de forma transparente.
Validación con Zod en DTOs + middleware genérico	Una única vía de validación declarativa para body y query, con mensajes en español y details por campo.
ACL declarativa en el frontend + requireRole en backend	El frontend oculta acciones por permiso (meta.can, sidebar) y el backend impone la autorización real (defensa en profundidad).
SUPERADMIN con bypass en requireRole	Garantiza que el superadministrador siempre tenga acceso, sin enumerarlo en cada ruta.
Sistema de modales apilables con store	Permite anidar modales (p. ej. gestión → importación → conflicto) con foco/Escape controlados. Ver frontend/src/stores/modalStore.ts y BaseModal.vue.
Motor de simulación no destructivo + propuesta revisable	La asignación rápida separa simulate (cálculo) de apply-simulation (persistencia), permitiendo revisar el reparto antes de aplicarlo. Ver modulos/asignacion-rapida.md.
Almacenamiento en FS local (storage/) servido por /api/files/download/:objectName	Evita dependencia de almacenamiento objeto en despliegues autónomos.
Jobs cron horarios	Expiran confirmaciones pendientes y penalizaciones vencidas sin intervención manual.
Logo de los correos embebido por CID	Las plantillas de correo referencian cid:siva-logo y backend/src/config/email.config.ts adjunta public/images/logo.png como adjunto inline (backend/src/utils/email-assets.ts) cuando el HTML lo usa. Así el logo no depende de una URL alcanzable ni lo bloquean los clientes que capan imágenes remotas. En las vistas previas (editor de plantillas y diálogos de notificación) el cid: se sustituye por /images/logo.png.

⚠️ Nota: las justificaciones se infieren del código y de PRODUCT.md; no hay ADRs que las documenten formalmente. Confirmar con el equipo si se quieren formalizar.

6. Autenticación y autorización

• Access token: JWT firmado con JWT_SECRET, tipo access, caducidad JWT_ACCESS_EXPIRATION.
• Refresh token: JWT tipo refresh, almacenado (hasheado en claro) en users.refresh_token; rotativo en cada refresco.
• Roles (backend/src/enums/user-role.enum.ts): SUPERADMIN, ADMIN, SUPERVISOR.
• Permisos de frontend (frontend/src/auth/): catálogo recurso:acción. SUPERADMIN y ADMIN tienen "*"; SUPERVISOR tiene todos los permisos operativos salvo TEMPLATES_* y USERS_*. Los requireRole de las rutas operativas incluyen a SUPERVISOR; solo Usuarios y Plantillas quedan restringidos a ADMIN.
• Configuración: el SUPERVISOR puede consultar y editar los parámetros habituales, pero configuracion.controller rechaza (403) las claves de CLAVES_CONFIGURACION_SOLO_ADMIN (colores globales, envío de correos, penalizaciones, modo de asignación por defecto y URL de la página de ayuda).

Nota histórica: AGENTS.md llegó a mencionar cuatro roles (superadmin, administrator, supervisor, user); actualmente está alineado con el código (SUPERADMIN, ADMIN, SUPERVISOR).

7. Documentación relacionada

• API.md — endpoints, autenticación y ejemplos.
• MODELO_DE_DATOS.md — entidades y relaciones.
• COMPONENTES.md — frontend, stores y rutas.
• DEUDA_TECNICA.md — hallazgos e inconsistencias.
• modulos/asignacion-rapida.md — motor de simulación.
• backend/typeorm-orderby-bug.md — workaround de TypeORM.