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

Source: arXiv:2606.28064 · Published 2026-06-26 · By Jan Keim, Dominik Fuchß, Sophie Corallo, Tobias Hey, Julian Winter, Kevin Feichtinger

TL;DR

The paper addresses the practical challenge of enabling automated traceability link recovery (TLR) across interrelated software artifacts such as software architecture documentation (SAD), software architecture models (SAM), and source code. Although state-of-the-art TLR techniques show promising accuracy, they are generally difficult to deploy without developer expertise, limiting adoption by architects and developers who would benefit most. To lower this barrier, the authors present the ARDoCo Tool Landscape, a publicly deployed ecosystem comprising three complementary tools: (1) a REST API exposing four TLR pipelines (SAD-SAM, SAM-Code, SAD-Code, and full SAD-SAM-Code) with asynchronous execution and caching, (2) TraceView, a browser-based frontend tailored for architects to explore multi-artifact trace links and inconsistencies interactively, and (3) TraceViz, a VS Code extension that overlays trace links directly in the IDE enabling seamless navigation between documentation and code. Through this integrated landscape, they make empirically validated TLR approaches accessible to a broader user base with minimal local installation or configuration required.

Key empirical results include strong TLR performance on a benchmark comprising five open-source Java projects, e.g. SWATTR achieving an average F1 score of 0.81 for SAD-SAM links, ArCoTL with 0.98 for SAM-Code, and TransArC scoring 0.82 for SAD-Code links, significantly outperforming the baseline ArDoCode (F1 = 0.37). For user experience, a small think-aloud study (n=7) showed that TraceViz’s in-IDE visualization substantially improved developer comprehension and navigation efficiency during software understanding tasks, with 6/7 participants finding it helpful. Overall, the ARDoCo tool suite demonstrates a practical realization of TLR research that supports maintenance, architecture consistency checking, and developer productivity across multiple artifact types.

Key findings

• SWATTR achieves an average F1 score of 0.81 on SAD-SAM traceability link recovery across five open-source Java projects.
• ArCoTL pipeline attains an average F1 score of 0.98 on SAM-Code traceability link recovery on the same benchmark.
• TransArC, which composes SAD-SAM and SAM-Code pipelines transitively, achieves an F1 score of 0.82 on SAD-Code trace recovery, outperforming the baseline ArDoCode method that scores 0.37.
• Inconsistency detection using SWATTR extensions yields an F1 score of 0.89 for detecting Model Entity Absent from Text (MEAT) inconsistencies.
• The ARDoCo REST API provides asynchronous execution and caching of TLR pipelines, improving usability and avoiding repeated computation for identical requests.
• TraceView’s browser-based multi-panel interface supports simultaneous visualization of SAD, SAM, and source code, with interactive cross-highlighting of trace links and inconsistencies.
• TraceViz VS Code extension visualizes SAD-Code trace links as gutter annotations, enabling one-click navigation between documentation and source code, supporting simultaneous display of up to two trace link sets.
• A preliminary think-aloud user study with seven participants reported that six found the TraceViz visualization helpful for software comprehension tasks, with all seven agreeing it supported their search and understanding process.

Threat model

The paper’s threat model centers on developers and architects as users needing robust automatic recovery of traceability links between architecture documentation, models, and source code to improve maintenance and comprehension. It does not consider adversarial attackers actively attempting to mislead or break traceability. Instead, it assumes artifact inputs are honest but heterogeneous and complex, requiring automated linking to reduce manual effort.

Methodology — deep read

The paper presents a tool engineering contribution integrating prior empirical TLR methods into a deployable tool landscape rather than introducing new algorithms. The threat model assumes developers or architects as users seeking to recover and maintain traceability between heterogeneous artifacts (natural language architecture docs, formal models, and source code). No active adversary is modeled.

The core data are artifact sets from five open-source Java projects (MediaStore, TeaStore, TEAMMATES, BigBlueButton, JabRef), including SAD texts, SAM representations (UML or Palladio components), and source code. These were used in earlier ARDoCo benchmark studies for TLR evaluation.

The ARDoCo REST API implements four main TLR pipelines: (1) SAD-SAM via SWATTR, which uses NLP and heuristics to link architecture doc sentences to model elements while detecting text-model inconsistencies; (2) SAM-Code via ArCoTL, which transforms SAM and code into intermediate representations, applying text similarity heuristics; (3) SAD-Code via ArDoCode as a baseline that applies heuristics directly without SAM; and (4) TransArC that transitively composes SWATTR and ArCoTL for SAD-Code.

TraceView is a Next.js and React browser frontend that enables users to upload artifacts, select pipeline configurations, and visualize results in up to three resizable panels showing the SAD, SAM, and source code side by side. Selecting elements in any panel highlights linked counterparts across artifacts. It polls the REST API asynchronously and caches results.

TraceViz is a VS Code extension integrating SAD-Code TLR results directly into the IDE via gutter markers aligned with documentation lines. It supports fetching results from the ARDoCo REST API, CSV imports from any TLR tool (compatibility format based on a previous gold standard), and local invocation of LiSSA (a retrieval-augmented generation approach). TraceViz offers navigation menus and supports dual trace link visualization for comparison.

The ARDoCo REST API is implemented in Java Spring Boot, providing endpoints for asynchronous/synchronous runs, result retrieval, and caching via Redis storing results for 24h keyed by request hashes.

Evaluation protocols rely on the established ARDoCo benchmark dataset with five open-source projects, reporting precision, recall, and F1 scores. The think-aloud user study (n=7) tested TraceViz with task comparisons of software comprehension with versus without in-IDE visualization, collecting qualitative feedback on usefulness and workflow impact.

The paper does not explicitly detail training regimes or hyperparameters for the underlying TLR algorithms, as these were covered in prior publications. Instead, it focuses on tool integration, deployment, and usability evaluation. All tools are publicly available as Docker images or VS Code extension packages, supporting reproducibility of execution though some benchmark data and full evaluation details are from earlier related papers.

Technical innovations

• Exposing multiple complementary TLR pipelines (SAD-SAM, SAM-Code, SAD-Code, SAD-SAM-Code) via a unified, asynchronously callable REST API with transparent caching.
• TraceView: a zero-install browser frontend enabling simultaneous side-by-side visualization of SAD, SAM, and source code artifacts with interactive multi-panel trace-link navigation and inconsistency detection.
• TraceViz: a VS Code extension integrating SAD-Code trace links as inline gutter markers enabling one-click navigation within the IDE, supporting multiple trace link sources including RAG-based LiSSA and CSV imports.
• Composition of heuristic-based TLR approaches transitively (TransArC) to improve trace link recovery between natural language documentation and source code through the software architecture model.

Datasets

• ARDoCo benchmark — 5 open-source Java projects (MediaStore, TeaStore, TEAMMATES, BigBlueButton, JabRef) — publicly available as per prior publications

Baselines vs proposed

• ArDoCode baseline SAD-Code trace link recovery: F1 = 0.37 vs TransArC (transitive SAD-SAM-Code) F1 = 0.82 on ARDoCo benchmark
• SWATTR SAD-SAM trace link recovery: F1 = 0.81
• ArCoTL SAM-Code trace link recovery: F1 = 0.98
• Inconsistency detection MEAT F1 = 0.89

Figures from the paper

Figures are reproduced from the source paper for academic discussion. Original copyright: the paper authors. See arXiv:2606.28064.

Fig 2: TraceView: SAD documentation (left), SAM (center), and recovered SAD-SAM trace links (right) shown side by side.

Fig 3: TraceViz in VS Code: colored gutter dots mark SAD-Code trace links. Hovering line 27 reveals per-set counts (blue: 26,

Limitations

• The think-aloud user study for TraceViz usability had a small sample size (n=7), limiting generalizability.
• The focus is on Java open-source projects; performance and usability on other languages or proprietary codebases remain untested.
• The REST API caching stores results only for 24 hours, so repeated queries outside this window require re-computation.
• The LLM-based TLR approaches (LiSSA) and component name recognition (ExArch) are not yet integrated into the REST API or frontend tooling.
• No adversarial threat or robustness evaluation is presented; potential issues against noisy or malicious documentation/code are unexplored.
• Scalability and visualization effectiveness for very large industrial systems with many trace links remain future work.

Open questions / follow-ons

• How can the approach scale to large-scale industrial codebases with extensive documentation and complex architecture models without overwhelming the user interface?
• What are the impacts of integrating the LLM-based LiSSA and ExArch modules into the REST API and frontends on TLR accuracy and end-user experience?
• How effectively do these tools perform in domains beyond Java, for example in polyglot or non-object-oriented codebases?
• What guardrails or robustness mechanisms can be implemented to handle inconsistencies, outdated documentation, or deliberately obfuscated artifact links?

Why it matters for bot defense

While this work is not directly related to CAPTCHA or bot defense, it offers valuable insights into building accessible, integrated tooling around complex machine learning or heuristic pipelines that operate on heterogeneous artifact types. The ARDoCo tool landscape exemplifies designing multi-interface deployments (REST API, web frontend, IDE plugin) that meet the varied needs of technical and non-technical users, with careful attention to usability and workflow integration. This approach parallels bot-defense systems that combine backend models with developer-facing dashboards or browser extensions.

Bot-defense engineers can adapt similar principles of traceability to track relationships between detection models, decision rules, threat intelligence data, and incident responses. Embedding trace visualizations in developer tools or security analyst consoles could enhance understanding and debugging of complex defenses, enabling more effective maintenance and evolution of bot-detection systems over time.

Cite

@article{arxiv2606_28064,
  title={ The ARDoCo Tool Landscape: REST API, TraceView, and TraceViz for Architecture Traceability },
  author={ Jan Keim and Dominik Fuchß and Sophie Corallo and Tobias Hey and Julian Winter and Kevin Feichtinger },
  journal={arXiv preprint arXiv:2606.28064},
  year={ 2026 },
  url={https://arxiv.org/abs/2606.28064}
}

Read the full paper

• arXiv:2606.28064 (abstract)
• arXiv:2606.28064 (PDF)