ADR-003 — Migración a multirepo (contenedor pet-flows)¶

Estado: aceptado
Fecha: 2026-07-31
Spec y plan: docs/specs/2026-07-30-multirepo-pet-flows-design.md y docs/specs/2026-07-30-multirepo-pet-flows.md en este repositorio. No se publican en el sitio: son material interno de la migración, como docs/prompts/ y docs/reference/.
Modelo de referencia: workspace.foodwise

Contexto¶

El monorepo dkv-pet-flows mezclaba la SPA de administración, el backend, la infraestructura Docker, herramientas auxiliares y documentación, con un Makefile de orquestación que cruzaba componentes. En paralelo, los artefactos del sync central de IA se versionaban de forma distinta en cada repositorio del ecosistema, generando cientos de cambios de ruido en cada sincronización.

Decisión¶

Adoptar el modelo del workspace foodwise: un directorio contenedor sin git con repositorios hermanos autónomos.

Repositorio	Contenido
`dkv-pet-flows-admin`	SPA React 18 + Vite
`dkv-pet-flows-api`	Spring Boot 4 + Pekko; infraestructura Docker; `synthetic-generator`
`dkv-pet-flows-doc`	Toda la documentación: MkDocs, showcases, ADRs, specs
`dkv-pet-flows-doc-terraform`	OpenTofu: Cloudflare Pages + Zero Trust del sitio
`ui-flows`	Librería de canvas de flujos (monorepo de 9 paquetes)
`ui-flows-demo`	Demo de la librería
`ui-flows-doc`	Documentación de diseño de la librería

Reglas que se derivan:

Acoplamiento cero. Cada repositorio arranca solo. El stack completo son dos terminales: make dev en el api, que levanta también la infraestructura Docker, y make dev en el admin. make dev/bundle, que empaquetaba la SPA dentro del Spring Boot, desaparece; si se necesita, se reconstruye como paso de CI.
Documentación solo en -doc, salvo el README de cada repositorio.
Artefactos del sync de IA en la raíz del contenedor. Al vivir por encima de todos los repositorios, quedan fuera del árbol de trabajo de cada git: la clase de bug desaparece por construcción, no por una regla que haya que mantener sincronizada.

Historia¶

dkv-pet-flows-admin y dkv-pet-flows-api nacieron con historia nueva. La del monorepo eran nueve commits que arrastraban 1234 blobs de builds y entornos virtuales: 34 MB de .git para conservar tres commits sobre el admin y cinco sobre el api. La extracción se hizo con git archive, que copia solo lo versionado y deja fuera node_modules y 1,4 GB de clones auxiliares.

El monorepo jaraxasoftware/dkv-pet-flows queda archivado como referencia de solo lectura.

La excepción de ui-flows¶

La política de artefactos de IA tiene una excepción deliberada. ui-flows versiona .agents/skills/ a propósito: apps/docs/src/data/skillRegistry.ts publica ese catálogo en su sitio de documentación y el workflow docs-cloudflare-pages.yml vigila esas rutas. Desvincularlas rompería el sitio en un checkout de CI. Es el escenario persist de la política del SSoT, frente al ephemeral que aplican los demás.

dkv-pet-flows-admin es una excepción parcial: sus reglas bajo .agents/ —api-layer, react-patterns, state-management, zustand-store— las escribió el equipo para ese código y se versionan; solo se ignoran las del catálogo central.

Reproducibilidad¶

El bloqueo que documentaba el ADR-002 queda resuelto. dkv-pet-flows-admin declaraba @jaraxa/ui-flows mediante una ruta absoluta al $HOME del autor, lo que hacía fallar npm install en cualquier otra máquina. Al convertirse en repositorios hermanos, la ruta pasa a ser relativa. Verificado con instalación limpia: cero rutas absolutas en el lockfile, y node_modules/@jaraxa/ui-flows resolviendo a ../../../ui-flows/packages/ui-flows.

La resolución definitiva es publicar el paquete en el Nexus corporativo como @jaraxa/ui-flows y consumirlo por versión, dejando el enlace relativo como override de desarrollo. Se eligió Nexus sobre GitHub Packages porque es servidor privado propio ya normalizado y, sobre todo, porque no impone que el scope coincida con la cuenta propietaria: permite publicar bajo @jaraxa, que es el nombre que el código ya importa, eliminando el alias que hacía falta.

Consecuencias¶

Ningún repositorio lleva workflows de despliegue de la aplicación. El de Cloudflare Pages del admin se eliminó por legacy: nunca llegó a ejecutarse, no tenía secrets configurados y apuntaba a una plantilla de Vite sin adaptar. El destino previsto es DOKS, pendiente de definir.
El sitio de documentación conserva su propio despliegue en Cloudflare, vía dkv-pet-flows-doc-terraform, que esta migración no toca.
dkv-pet-flows-admin conserva la cadena de entrega Jenkins-X heredada de dkv-pet-admin, con el naming adaptado. No está operativa: requiere una instalación de Jenkins-X donde el repositorio esté dado de alta. Se mantiene como punto de partida y referencia de configuración.
El manifest.yaml del SSoT de skills debe declarar el contenedor y su política de git; sin eso, el primer sync posterior a la migración deshace parte del trabajo.

Deuda registrada¶

Rotación del app_secret de la integración external_push. Aparecía en claro en la auditoría de dkv-notifications y está redactado en la documentación, pero el valor sigue en cinco ficheros de dkv-pet-cloud, incluido como valor por defecto de ${COLLAB_EXTERNAL_PUSH_APP_SECRET}: cualquier entorno que no defina la variable arranca con la credencial compartida.
SONAR_TOKEN en claro en .lighthouse/jenkins-x/pullrequest.yaml del admin, igual que en dkv-pet-admin. Deuda compartida de ambos repositorios.
Inyección de configuración por ConfigMap. dkv-pet-admin incorporó en 52faa47f el paso de variables de build-time a lectura en arranque desde un ConfigMap. El admin de flows aún no lo tiene.