💻 computer science

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

Este artigo apresenta o ARDoCo Tool Landscape, um conjunto publicamente disponível que compreende uma API REST, um frontend baseado em navegador (TraceView) e uma extensão para VS Code (TraceViz) que torna a recuperação de links de rastreabilidade de última geração acessível a desenvolvedores e arquitetos, ao mesmo tempo que demonstra uma melhoria na compreensão por meio de visualização dentro da IDE.

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

Publicado 2026-06-29

📖 4 min de leitura☕ Leitura rápida

CC BY 4.0

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

Artigo original sob licença CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). ✨ Esta é uma explicação gerada por IA do artigo abaixo. Não foi escrita nem endossada pelos autores. Para precisão técnica, consulte o artigo original. Ler aviso legal completo

Imagine que você é o arquiteto de uma cidade massiva e complexa. Você tem três conjuntos diferentes de plantas para esta cidade:

O Livro de Histórias (SAD): Uma descrição escrita de como a cidade deveria funcionar, escrita em inglês simples.
Os Diagramas (SAM): Desenhos formais e modelos mostrando como os edifícios e estradas se conectam.
A Construção (Código): Os próprios tijolos, argamassa e fiação que compõem a cidade real.

O problema é que essas três coisas frequentemente se distanciam. O Livro de Histórias pode dizer "construa uma ponte", mas os Diagramas esqueceram dela, e a equipe de Construção construiu um túnel em vez disso. Manter todos em sincronia é um pesadelo para os humanos porque há muita informação para rastrear manualmente.

Este artigo apresenta um "kit de ferramentas mágico" chamado ARDoCo que encontra automaticamente as conexões entre essas três plantas e identifica onde elas discordam. Para tornar este kit de ferramentas fácil de usar para todos, a equipe construiu três "portas" diferentes no sistema:

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

Pense nisso como uma usina de energia central. É o maquinário pesado que faz o trabalho real de comparar o Livro de Histórias, os Diagramas e a Construção.

Para quem é: Outras ferramentas de software ou programadores que desejam conectar este motor aos seus próprios sistemas.
Como funciona: Você envia suas plantas para este motor através da internet. Ele executa a comparação, salva os resultados (para não ter que refazer o trabalho se você perguntar novamente) e envia a resposta de volta. É como pedir uma pizza: você envia o pedido, a cozinha prepara e entrega o resultado.

2. A Torre de Controle: TraceView

Este é um painel baseado na web que qualquer pessoa pode abrir em um navegador sem instalar nada.

Para quem é: Arquitetos e gestores que precisam ver o "panorama geral".
Como funciona: Imagine uma tela dividida em três janelas. À esquerda está seu Livro de Histórias, no meio estão seus Diagramas e à direita está a Construção. Quando você clica em uma frase no Livro de Histórias, a ferramenta destaca instantaneamente a parte correspondente nos Diagramas e na Construção nas outras telas. Também atua como um holofote para erros, piscando em vermelho quando o Livro de Histórias menciona um edifício que não existe nos Diagramas.

3. O Display de Cabeça (HUD): TraceViz

Este é um complemento especial para o espaço de trabalho dos desenvolvedores de software (especificamente para um programa chamado VS Code).

Para quem é: Os próprios construtores (desenvolvedores) escrevendo o código.
Como funciona: Em vez de fazer você trocar de janela, esta ferramenta pinta pequenos pontos coloridos logo ao lado das linhas de código que você está digitando. Se você passar o mouse sobre um ponto, ele diz: "Ei, esta linha de código se conecta a esta frase no Livro de Histórias". É como um GPS para o código, permitindo que você salte instantaneamente de um requisito escrito para a peça exata de código que o cumpre, sem nunca sair da sua mesa.

Funcionou?

A equipe testou essas ferramentas em projetos de software do mundo real.

O Motor: A correspondência automática é muito boa em encontrar conexões, acertando frequentemente mais de 80% das vezes, o que é uma grande melhoria em relação a não fazer nada.
O Display de Cabeça: Eles pediram a um pequeno grupo de desenvolvedores para usar a ferramenta. O resultado? Todos concordaram que ajudou a entender melhor o código. Antes de usar a ferramenta, eles tinham que vasculhar pastas manualmente para encontrar conexões. Com os pontos coloridos, eles podiam saltar direto para a resposta. Um desenvolvedor até disse que seria ótimo para treinar novos contratados.

O Ponto Principal

A equipe do ARDoCo transformou pesquisa de ciência da computação complexa e de difícil uso em um kit de ferramentas amigável. Quer você queira rodar o motor por conta própria, olhar um painel no seu navegador ou ver as conexões enquanto programa, existe uma ferramenta para você manter as plantas e a construção da sua cidade de software em perfeita sincronia.

Resumo Técnico: O Ecossistema de Ferramentas ARDoCo

Contexto do Problema
O desenvolvimento de software gera artefatos inter-relacionados em múltiplos níveis de abstração: documentação de arquitetura de software (SAD) em linguagem natural, modelos de arquitetura de software (SAM) formais e código-fonte. Manter a consistência e a rastreabilidade entre esses artefatos é crítico para manutenção, análise de impacto de mudanças e evolução. No entanto, manter links de rastreabilidade manualmente é tedioso e propenso a erros. Embora a Recuperação de Links de Rastreabilidade (TLR) automatizada seja essencial, as abordagens ARDoCo existentes (SWATTR, ArCoTL, TransArC, LiSSA) têm sido historicamente disponíveis apenas como bibliotecas Java ou ferramentas de linha de comando. Essa barreira técnica impede a adoção por arquitetos e desenvolvedores que carecem de expertise para configurar e executar essas ferramentas, limitando o deployment prático de TLR de última geração.

Metodologia e Ecossistema de Ferramentas
Para preencher a lacuna entre a pesquisa algorítmica e a aplicação prática, os autores apresentam um ecossistema de ferramentas implantado publicamente, composto por três interfaces complementares que expõem a família de TLR ARDoCo:

API REST ARDoCo: Um backend baseado em Spring Boot que fornece acesso programático a quatro pipelines de TLR via endpoints HTTP. Suporta execução assíncrona e cache de resultados (via Redis) para otimizar o desempenho. Os pipelines expostos incluem:
- SAD-SAM: Utilizando SWATTR (NLP e heurísticas) com detecção de inconsistências de Entidade de Texto Ausente do Modelo (TEAM - Text Entity Absent from Model) e Entidade de Modelo Ausente do Texto (MEAT - Model Entity Absent from Text).
- SAM-Code: Utilizando ArCoTL (representações intermediárias e similaridade de texto).
- SAD-Code (Direto): Utilizando ArDoCode (aplicando heurísticas do SWATTR diretamente ao código sem um SAM).
- SAD-SAM-Code Transitivo: Utilizando TransArC (compondo SWATTR e ArCoTL de forma transitiva).
  A API retorna JSON estruturado e inclui uma interface Swagger UI integrada para exploração.
TraceView: Um frontend baseado em navegador, sem necessidade de instalação, construído com Next.js e React, otimizado para arquitetos e não-desenvolvedores. Apresenta um assistente guiado para upload de artefatos (SAD, SAM, código) e configuração do pipeline de TLR. A interface principal oferece uma visualização interativa de múltiplos painéis, onde os usuários podem visualizar SAD, SAM e código-fonte lado a lado. Selecionar um elemento destaca seus contrapartes vinculados e inconsistências detectadas em todos os painis, facilitando a navegação entre artefatos.
TraceViz: Uma extensão para Visual Studio Code otimizada para desenvolvedores, especificamente para o TLR SAD-Code. Ela sobrepõe os links de rastreabilidade diretamente no IDE como marcadores coloridos na margem (gutter markers). Principais recursos incluem:
- Navegação: Navegação com um clique de sentenças da documentação para arquivos de código vinculados (e vice-versa) via menus Quick Pick ou CodeLens.
- Agnosticismo de Fonte: Suporta links da API REST (ArDoCode/TransArC), importações de CSV de ferramentas externas e execução local do LiSSA (uma abordagem de Geração Aumentada por Recuperação - RAG).
- Otimização Visual: Reduz o ruído ao agregar marcadores por arquivo em pontos de nível de diretório quando apropriado e permite a comparação lado a lado de até dois conjuntos de links de rastreabilidade.

Principais Contribuições

Acessibilidade: O ecossistema transforma algoritmos de TLR complexos e baseados em bibliotecas em ferramentas acessíveis que exigem pouca ou nenhuma instalação local, atendendo a diferentes personas de usuário (integradores, arquitetos e desenvolvedores).
Backend Unificado: A API REST serve como um motor computacional compartilhado, garantindo consistência entre as interfaces de navegador e de IDE, permitindo também a integração de terceiros.
Visualização In-IDE: O TraceViz introduz uma abordagem inovadora para visualizar a rastreabilidade diretamente no contexto de edição do desenvolvedor, indo além de relatórios externos.

Resultados e Avaliação

Desempenho Algorítmico: Os algoritmos de TLR subjacentes foram avaliados em um benchmark de cinco projetos Java de código aberto (MediaStore, TeaStore, TEAMMATES, BigBlueButton, JabRef). Os resultados indicam que o SWATTR alcança um F1 de 0,81 para SAD-SAM, o ArCoTL alcança 0,98 para SAM-Code, e o TransArC alcança 0,82 para SAD-Code, superando significativamente o baseline do ArDoCode (F1 = 0,37). A detecção de inconsistência (MEAT) alcançou um F1 de 0,89.
Estudo com Usuários (TraceViz): Um estudo preliminar de think-aloud ( $n=7$ $n = 7$ ), envolvendo doutorandos, mestrandos e um desenvolvedor da indústria, avaliou a utilidade do TraceViz. Os participantes realizaram tarefas de compreensão de software no projeto TEAMMATES com e sem a visualização.
- Seis de sete participantes consideraram a visualização útil para a conclusão das tarefas.
- Todos os sete concordaram que ela apoiou seu processo de compreensão.
- O feedback qualitativo indicou que, sem a visualização, os usuários dependiam de travessia manual repetitiva de árvores, enquanto o TraceViz permitiu saltos diretos para arquivos relevantes.
- Três participantes expressaram intenção de usar a ferramenta em contextos reais, enquanto outros notaram o potencial para onboarding e navegação em grandes bases de código.

Significância
O artigo afirma que este ecoss de ferramentas torna a TLR de última geração acessível a um público mais amplo de arquitetos, desenvolvedores e integradores de ferramentas que anteriormente eram excluídos pela complexidade técnica dos algoritmos subjacentes. Ao fornecer uma ferramenta de exploração baseada em navegador (TraceView) e uma visualização integrada ao IDE (TraceViz), os autores demonstram que a rastreabilidade automatizada pode ser efetivamente implantada na prática. O estudo de usuário preliminar sugere que visualizar esses links diretamente no IDE melhora a compreensão e a eficiência do desenvolvedor durante tarefas de entendimento de software. Trabalhos futuros visam integrar abordagens baseadas em LLM (LiSSA, ExArch) ao ecossistema e realizar estudos controlados maiores.