ADR-002 — Layout del frontend: una sola SPA

• Estado: aceptado
• Fecha: 2026-07-30
• Sustituye a: el esqueleto de monorepo npm en apps/ + packages/

Contexto

El repositorio mantenía dos layouts JavaScript en paralelo:

1. dkv-pet-flows-admin/ — la SPA React 18 + Vite que se despliega de verdad.
2. apps/web + packages/* — workspaces npm declarados en el package.json de la raíz, presentados como la extracción del canvas de flujos a paquetes reutilizables @jaraxa/flow-*.

La documentación afirmaba que el admin consumía esos paquetes y que los enlaces de workspace debían resolver para que npm install funcionase. La inspección lo desmiente:

Ruta	Contenido real
packages/core/	directorio vacío
packages/flow-canvas/	6 líneas; devuelve un div con el texto Canvas Placeholder
packages/flow-icons/	5 líneas; reexporta lucide-react y un console.log
packages/flow-nodes/	3 líneas; TriggerNode, ActionNode y ConditionNode devuelven null
apps/web/	plantilla de arranque de Vite + React sin modificar

Ningún fichero del repositorio importaba @jaraxa/flow-*. El node_modules/ de la raíz hospedaba 169 paquetes al servicio de 15 líneas de placeholder.

La dependencia real del admin es @jaraxa/ui-flows, declarada como enlace local:

"@jaraxa/ui-flows": "file:/home/amf/workspace.jaraxa/ui-flows/packages/ui-flows"

Se importa en src/pages/Escenarios.jsx, src/components/ExecutionOverlay.jsx y src/components/SimulationWidget.jsx.

Decisión

Eliminar apps/, packages/, el package.json de la raíz y su package-lock.json. El repositorio pasa a tener un único proyecto JavaScript, dkv-pet-flows-admin/, con su propio package.json y su propio lockfile.

El workflow cloudflare-deploy-frontend.yml apuntaba a apps/web y se ha reapuntado a dkv-pet-flows-admin, corrigiendo además el directorio de salida: Vite está configurado con outDir: 'build', no dist.

Consecuencia pendiente: el repositorio no es reproducible

npm install en dkv-pet-flows-admin falla en cualquier máquina que no sea la del autor original, porque la ruta del enlace es absoluta y apunta fuera del repositorio. El lockfile registra "link": true con una ruta relativa que también escapa del árbol.

Actualización 2026-07-31 — resuelto (ver ADR-003). Esta conclusión era cierta para alpha.1, la versión que registraba el lockfile del admin, y ha caducado:

• Desde ui-flows v0.1.0-alpha.5 las ocho dependencias internas @jaraxa/flow-* pasaron a devDependencies y dependencies quedó vacío. El dist/ publicable está bundleado con tsup y sus únicos externals son react, react-dom, react/jsx-runtime, zustand y @xyflow/react. Publicar es un paquete, no nueve.
• La migración a multirepo colocó ui-flows y dkv-pet-flows-admin como hermanos dentro del contenedor pet-flows/, así que la ruta relativa dejó de ser inviable. Verificado con instalación limpia: el lockfile pasó de dos rutas absolutas al $HOME del autor a cero, y node_modules/@jaraxa/ui-flows resuelve a ../../../ui-flows/packages/ui-flows.

Sigue descartada la dependencia git: npm no admite subdirectorios en dependencias git y el paquete vive en packages/ui-flows de un monorepo; además dist/ no está versionado y no hay script prepare, así que la instalación no construiría nada.

La resolución definitiva es publicar el paquete como @jaraxa/ui-flows en el Nexus corporativo y consumirlo por versión, dejando la ruta relativa como override para desarrollar la librería en paralelo. El enlace relativo cubre el desarrollo local; el consumo por versión cubre además el CI.

Mientras tanto el despliegue automático a Cloudflare Pages queda desactivado y el workflow solo se dispara con workflow_dispatch.

Notas

ui-flows vive hoy en github.com/jrx-amf/ui-flows, una cuenta personal, mientras que el repositorio que lo consume ya está en la organización jaraxasoftware. Trasladarlo es requisito previo a cualquier publicación.

Los antiguos packages/flow-{canvas,icons,nodes} eran una copia local temprana de tres de los ocho paquetes internos que ui-flows acabó implementando.