# Arquitectura y stack técnico

> Alineado con el stack habitual de LearnTechSphere para reutilizar patrones ya probados (YouFlow, InfoMercantil, Pensilvania RRHH).

## Stack propuesto

| Capa | Tecnología | Motivo |
|------|-----------|--------|
| Frontend | **Next.js + React + shadcn/ui + Tailwind** | Mismo patrón que YouFlow; shadcn da la estética limpia tipo backoffice que encaja con replicar vistas de Kraken |
| Backend | **NestJS** (o FastAPI si se prefiere Python) | API REST + WebSocket para telemetría en vivo |
| BD | **PostgreSQL 16** | Esquema de `03_MODELO_DATOS.md`; JSONB para layouts y telemetría |
| Cache/colas | **Redis** | Sesiones de examen, cronómetros server-side, cola de recálculo de acreditaciones |
| IA (opcional, fase 3) | **Claude API** | Pre-corrección de casos abiertos (master/pro) con rúbrica; generación de variantes de ítems |
| Infra | Docker en VPS (Contabo) o VPS dedicado del cliente | Igual que InfoMercantil; subdominio tipo `sim.{cliente}.com` |
| Auth | Email+password con roles; SSO Google opcional | Simple para v1 |

## Decisiones de diseño importantes

### 1. Vistas de Kraken como **layouts declarativos**, no como código hardcodeado
Cada pantalla del simulador se define en JSONB (`screens.layout`): componentes, campos, validaciones. Ventajas:
- La formadora podrá crear/ajustar pantallas desde el editor sin desarrollo.
- Añadir un proceso nuevo = configuración, no programación.
- Se construye **una librería de ~10-15 componentes tipo Kraken** a partir del vídeo de vistas (ficha cliente, formulario, tabla, timeline, buscador, modal de pago...) y con eso se compone todo.

### 2. Cronometraje server-side
Los timestamps de inicio/fin de paso se registran en servidor (no solo en cliente) para que los tiempos sean fiables y no manipulables. El cliente envía eventos; el servidor es la fuente de verdad temporal.

### 3. Telemetría por eventos
Todo lo que hace el agente (focus, input, click, error) se emite como evento a `attempt_events`. Las métricas agregadas (`attempts.total_time_sec`, contadores de error) se materializan al cerrar el intento. Esto permite responder mañana a preguntas que hoy no sabemos que tendremos.

### 4. Motor de reglas de nivel desacoplado
Las reglas junior/core/master/pro viven en datos (`level_rules`), no en código. Un job recalcula `accreditations` y `user_levels` cuando llega nueva evidencia. Cada asignación de nivel guarda snapshot de la regla → auditable ante RRHH.

### 5. Un solo producto, dos módulos
KrakenSim y Skill Matrix comparten BD, auth y backoffice. Se despliegan como una única aplicación con dos áreas. Menos coste, integración nativa.

## Seguridad y RGPD

- Datos de empleados: minimización, acceso por rol, logs de acceso a resultados individuales.
- Datos de "clientes" del simulador: 100% sintéticos (generador de DNI/CUPS/IBAN de prueba). Prohibido importar datos reales de Kraken.
- Al ligar resultados a retribución: informar a los trabajadores de que existe evaluación de desempeño con estas herramientas (obligación de transparencia laboral; lo gestiona RRHH del cliente, pero hay que avisarles).

## Estimación de esfuerzo (orientativa, a validar tras respuestas del doc 06)

| Bloque | Esfuerzo |
|--------|----------|
| Librería de componentes Kraken + motor de pantallas | 3–4 semanas |
| Motor de procesos + validaciones + cronometraje | 2–3 semanas |
| Modo formación (guía paso a paso) | 1–2 semanas |
| Modo examen + baselines + dashboards | 2–3 semanas |
| Skill Matrix: catálogo + importador Excel + campañas | 2–3 semanas |
| Motor de reglas de nivel + acreditaciones | 2 semanas |
| **Total v1 (A+B)** | **~12–17 semanas** con fases entregables intermedias |