💻 computer science

The ARDoCo Tool Landscape: REST API, TraceView, and TraceViz for Architecture Traceability

Este artículo presenta el ARDoCo Tool Landscape, un conjunto de herramientas disponible públicamente que comprende una API REST, un frontend basado en el navegador (TraceView) y una extensión de VS Code (TraceViz) que hace que la recuperación de enlaces de trazabilidad de vanguardia sea accesible para desarrolladores y arquitectos, al tiempo que demuestra una mejor comprensión mediante la visualización dentro del IDE.

Autores originales: Jan Keim, Dominik Fuchß, Sophie Corallo, Tobias Hey, Julian Winter, Kevin Feichtinger

Publicado 2026-06-29

📖 4 min de lectura☕ Lectura para el café

CC BY 4.0

Autores originales: Jan Keim, Dominik Fuchß, Sophie Corallo, Tobias Hey, Julian Winter, Kevin Feichtinger

Artículo original bajo licencia CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). ✨ Esta es una explicación generada por IA del artículo a continuación. No ha sido escrita ni avalada por los autores. Para mayor precisión técnica, consulte el artículo original. Leer descargo de responsabilidad completo

Imagina que eres el arquitecto de una ciudad masiva y compleja. Tienes tres conjuntos diferentes de planos para esta ciudad:

El Libro de Cuentos (SAD): Una descripción escrita de cómo debería funcionar la ciudad, escrita en inglés sencillo.
Los Diagramas (SAM): Dibujos y modelos formales que muestran cómo se conectan los edificios y las carreteras.
La Construcción (Código): Los ladrillos, el mortero y el cableado reales que conforman la ciudad real.

El problema es que estas tres cosas suelen distanciarse. El Libro de Cuentos podría decir "construir un puente", pero los Diagramas lo olvidaron, y la cuadrilla de Construcción construyó un túnel en su lugar. Mantener todos en sincronía es una pesadilla para los humanos porque hay demasiada información para rastrear manualmente.

Este artículo presenta un "kit de herramientas mágico" llamado ARDoCo que encuentra automáticamente las conexiones entre estos tres planos y detecta dónde discrepan. Para que este kit sea fácil de usar para todos, el equipo construyó tres "puertas" diferentes en el sistema:

1. La Sala de Máquinas: La API REST

Piensa en esto como una central eléctrica. Es la maquinaria pesada que realiza el trabajo real de comparar el Libro de Cuentos, los Diagramas y la Construcción.

Para quién es: Otras herramientas de software o programadores que quieran conectar este motor a sus propios sistemas.
Cómo funciona: Envías tus planos a este motor a través de internet. Este realiza la comparación, guarda los resultados (para no tener que repetir el trabajo si vuelves a preguntar) y te envía la respuesta. Es como pedir una pizza: envías el pedido, la cocina lo prepara y entrega el resultado.

2. La Torre de Control: TraceView

Este es un panel de control basado en la web que cualquiera puede abrir en un navegador sin instalar nada.

Para quién es: Arquitectos y gestores que necesitan ver el "panorama general".
Cómo funciona: Imagina una pantalla dividida en tres ventanas. A la izquierda está tu Libro de Cuentos, en el medio tus Diagramas y a la derecha la Construcción. Cuando haces clic en una frase del Libro de Cuentos, la herramienta resalta instantáneamente la parte correspondiente en los Diagramas y en la Construcción en las otras pantallas. También actúa como un foco para errores, parpadeando en rojo cuando el Libro de Cuentos menciona un edificio que no existe en los Diagramas.

3. La Pantalla de Visualización Frontal (HUD): TraceViz

Este es un complemento especial para el espacio de trabajo de los desarrolladores de software (específicamente para un programa llamado VS Code).

Para quién es: Los constructores reales (desarrolladores) que escriben el código.
Cómo funciona: En lugar de obligarte a cambiar de ventana, esta herramienta pinta pequeños puntos de colores justo al lado de las líneas de código que estás escribiendo. Si pasas el cursor sobre un punto, te dice: "Oye, esta línea de código se conecta con esta frase en el Libro de Cuentos". Es como un GPS para el código, permitiéndote saltar instantáneamente de un requisito escrito a la pieza exacta de código que lo cumple, sin tener que abandonar nunca tu escritorio.

¿Funcionó?

El equipo probó estas herramientas en proyectos de software del mundo real.

El Motor: El emparejamiento automático es muy bueno encontrando conexiones, acertando a menudo más del 80% de las veces, lo cual es una gran mejora respecto a no hacer nada.
La Pantalla de Visualización Frontal: Le pidieron a un pequeño grupo de desarrolladores que usaran la herramienta. ¿El resultado? Todos estuvieron de acuerdo en que les ayudó a entender mejor el código. Antes de usar la herramienta, tenían que buscar manualmente entre carpetas para encontrar las conexiones. Con los puntos de colores, podían saltar directamente a la respuesta. Un desarrollador incluso dijo que sería genial para la formación de nuevos empleados.

La Conclusión

El equipo de ARDoCo ha convertido una investigación de ciencias de la computación compleja y difícil de usar en un kit de herramientas amigable. Ya sea que quieras ejecutar el motor por tu cuenta, ver un panel de control en tu navegador o ver las conexiones mientras programas, hay una herramienta para ti para mantener los planos de tu ciudad de software y su construcción en perfecta sincronía.

Resumen Técnico: El Paisaje de Herramientas ARDoCo

Contexto del Problema
El desarrollo de software genera artefactos interrelacionados a través de múltiples niveles de abstracción: la documentación de arquitectura de software (SAD) en lenguaje natural, los modelos de arquitectura de software (SAM) formales y el código fuente. Mantener la consistencia y la trazabilidad entre estos artefactos es crítico para el mantenimiento, el análisis de impacto de cambios y la evolución. Sin embargo, mantener manualmente los enlaces de trazabilidad es tedioso y propenso a errores. Aunque la recuperación automatizada de enlaces de trazabilidad (TLR) es esencial, los enfoques de ARDoCo existentes (SWATTR, ArCoTL, TransArC, LiSSA) han estado históricamente disponibles solo como librerías de Java o herramientas de línea de comandos. Esta barrera técnica impide la adopción por parte de arquitectos y desarrolladores que carecen de la experiencia para configurar y ejecutar estas herramientas, limitando el despliegue práctico de la recuperación de enlaces de trazabilidad (TLR) de vanguardia.

Metodología y Paisaje de Herramientas
Para cerrar la brecha entre la investigación algorítmica y la aplicación práctica, los autores presentan un paisaje de herramientas desplegado públicamente que comprende tres interfaces complementarias que exponen la familia de TLR de ARDoCo:

API REST de ARDoCo: Un backend basado en Spring Boot que proporciona acceso programático a cuatro canales (pipelines) de TLR mediante endpoints HTTP. Soporta la ejecución asíncrona y el almacenamiento en caché de resultados (vía Redis) para optimizar el rendimiento. Los canales expuestos incluyen:
- SAD-SAM: Utilizando SWATTR (NLP y heurísticas) con detección de inconsistencias de Entidad de Texto Ausente del Modelo (TEAM) y Entidad de Modelo Ausente del Texto (MEAT).
- SAM-Code: Utilizando ArCoTL (representaciones intermedias y similitud de texto).
- SAD-Code (Directo): Utilizando ArDoCode (aplicando las heurísticas de SWATTR directamente al código sin un SAM).
- Transitivo SAD-SAM-Code: Utilizando TransArC (componiendo SWATTR y ArCoTL de forma transitiva).
  La API devuelve JSON estructurado e incluye una interfaz Swagger UI integrada para su exploración.
TraceView: Un frontend basado en el navegador, sin necesidad de instalación, construido con Next.js y React, optimizado para arquitectos y no desarrolladores. Cuenta con un asistente guiado para la carga de artefactos (SAD, SAM, código) y la configuración del canal de TLR. La interfaz central ofrece una vista interactiva de paneles múltiples donde los usuarios pueden visualizar SAD, SAM y código fuente de forma paralela. Seleccionar un elemento resalta sus contrapartes vinculadas e inconsistencias detectadas en todos los paneles, facilitando la navegación entre artefactos.
TraceViz: Una extensión de Visual Studio Code optimizada para desarrolladores, específicamente para la TLR de SAD-Code. Superpone los enlaces de trazabilidad directamente en el IDE mediante marcadores de color en el margen (gutter). Características clave incluyen:
- Navegación: Navegación de un solo clic desde las sentencias de la documentación hacia los archivos de código vinculados (y viceversa) mediante menús Quick Pick o CodeLens.
- Agnosticismo de la Fuente: Soporta enlaces desde la API REST (ArDoCode/TransArC), importaciones de CSV desde herramientas externas y la ejecución local de LiSSA (un enfoque de Generación Aumentada por Recuperación).
- Optimización Visual: Reduce el ruido agregando marcadores por archivo en puntos a nivel de directorio cuando es apropiado y permite la comparación lateral de hasta dos conjuntos de enlaces de trazabilidad.

Contribuciones Clave

Accesibilidad: El paisaje transforma complejos algoritmos de TLR basados en librerías en herramientas accesibles que requieren poca o ninguna instalación local, atendiendo a diferentes perfiles de usuario (integradores, arquitectos y desarrolladores).
Backend Unificado: La API REST sirve como un motor computacional compartido, asegurando la consistencia entre las interfaces del navegador y del IDE, al tiempo que permite la integración de terceros.
Visualización In-IDE: TraceViz introduce un enfoque novedoso para visualizar la trazabilidad directamente dentro del contexto de edición del desarrollador, yendo más allá de los informes externos.

Resultados y Evaluación

Rendimiento Algorítmico: Los algoritmos de TLR subyacentes han sido evaluados en un benchmark de cinco proyectos Java de código abierto (MediaStore, TeaStore, TEAMMATES, BigBlueButton, JabRef). Los resultados indican que SWATTR logra un F1 de 0.81 para SAD-SAM, ArCoTL logra un 0.98 para SAM-Code, y TransArC logra un 0.82 para SAD-Code, superando significativamente la base de ArDoCode (F1 = 0.37). La detección de inconsistencias (MEAT) alcanzó un F1 de 0.89.
Estudio de Usuario (TraceViz): Un estudio preliminar de tipo "think-aloud" ( $n=7$ $n = 7$ ) que involucró a candidatos de doctorado, graduados de maestría y un desarrollador de la industria, evaluó la utilidad de TraceViz. Los participantes realizaron tareas de comprensión de software en el proyecto TEAMMATES con y sin visualización.
- Seis de siete participantes encontraron la visualización útil para completar la tarea.
- Los siete estuvieron de acuerdo en que la herramienta apoyó su proceso de comprensión.
- El feedback cualitativo indicó que, sin la visualización, los usuarios dependían de un recorrido manual repetitivo de árboles, mientras que TraceViz permitió saltos directos a los archivos relevantes.
- Tres participantes expresaron intención de usar la herramienta en contextos reales, mientras que otros señalaron el potencial para la incorporación (onboarding) y la navegación en bases de código extensas.

Significancia
El artículo sostiene que este paisaje de herramientas hace que la recuperación de enlaces de trazabilidad (TLR) de vanguardia sea accesible para una audiencia más amplia de arquitectos, desarrolladores e integradores de herramientas que anteriormente estaban excluidos por la complejidad técnica de los algoritmos subyacentes. Al proporcionar una herramienta de exploración basada en el navegador (TraceView) y una visualización integrada en el IDE (TraceViz), los autores demuestran que la trazabilidad automatizada puede implementarse eficazmente en la práctica. El estudio de usuario preliminar sugiere que visualizar estos enlaces directamente en el IDE mejora la comprensión y la eficiencia del desarrollador durante las tareas de comprensión de software. El trabajo futuro apunta a integrar enfoques basados en LLM (LiSSA, ExArch) en el paisaje y realizar estudios controlados de mayor escala.