Source-linked AI summary
ArchAgent: Scalable Legacy Software Architecture Recovery with LLMs
Rusheng Pan, Bingcheng Mao, Tianyi Ma, Zhenhua Ling
TL;DR
Large-scale legacy architecture recovery is challenged by architectural drift, limited LLM context, and missing business semantics. ArchAgent combines static analysis, adaptive grouping, and LLM synthesis with cross-repository context to generate architecture views. Evaluations report higher F1 than DeepWiki and a case study found broad coverage of business-critical modules.
Problem
Large legacy repositories are difficult to recover architecturally because LLM context is limited and missing documentation makes core business logic hard to distinguish from auxiliary code.
Source: §1 · p. 1Method
Results
ArchAgent achieved mean F1 0.966 versus DeepWiki mean F1 0.860, with a statistically significant paired comparison.
Source: §4.1 · p. 4Takeaways & Limitations
In a 621-file SQL-transformation repository, the generated diagram surfaced business-critical modules, and the maintainer judged its coverage of commonly communicated information almost perfect.
Source: §4.3 · pp. 4–5
Abstract
from arXiv · showhide
Recovering accurate architecture from large-scale legacy software is hindered by architectural drift, missing relations, and the limited context of Large Language Models (LLMs). We present ArchAgent, a scalable agent-based framework that combines static analysis, adaptive code segmentation, and LLM-powered synthesis to reconstruct multiview, business-aligned architectures from cross-repository codebases. ArchAgent introduces scalable diagram generation with contextual pruning and integrates cross-repository data to identify business-critical modules. Evaluations of typical large-scale GitHub projects show significant improvements over existing benchmarks. An ablation study confirms that dependency context improves the accuracy of generated architectures of production-level repositories, and a real-world case study demonstrates effective recovery of critical business logics from legacy projects. The dataset is available at https://github.com/panrusheng/arch-eval-benchmark.
1. INTRODUCTION
Large-scale systems often drift away from their documentation, while LLM-based recovery is constrained by context windows and difficulty identifying business logic. ArchAgent combines static analysis, graph-based reasoning, and LLM synthesis to produce scalable, business-aligned architecture views.
1. INTRODUCTION
- Architectural drift from requirement changes and ad hoc modifications leaves large industrial systems poorly documented and difficult to recover.Architecture describes high-level structures, component interrelationships, and quality attributes such as scalability and maintainability.Source: §1 · p. 1
- LLM-based recovery faces context limits and difficulty distinguishing core business logic from auxiliary code, constraining coherent system-level architecture synthesis.Industrial codebases can exceed millions of tokens, beyond modern LLM context windows; missing documentation compounds the challenge.Source: §1 · p. 1
- ArchAgent integrates static analysis, graph-based reasoning, and LLM-powered semantic synthesis to recover architecture from cross-repository codebases.The framework combines file clustering and contextual pruning with cross-repository signals and DevOps-inspired heuristics to identify business-critical modules.Source: §1 · p. 1
2. RELATED WORK
Prior architecture-recovery methods rely on structural dependencies and clustering, while LLMs bring semantic capabilities but remain limited at repository scale. The section identifies a gap in scalable, semantics- and business-aware end-to-end recovery.
Static and Dynamic Architecture Recovery
- Classical recovery methods extract dependencies and cluster entities, but results can vary with input granularity and omit business semantics.Examples include ACDC, ARC, and Bunch.Source: §2 · pp. 1–2
LLMs for Code Understanding
- LLMs excel at code tasks such as completion and function summarization, yet repository-level use is constrained by local-scope bias and finite context windows.The passage notes that whole-file or package summaries may omit functions, misstate control flow, or hallucinate identifiers, while million-line repositories exceed one-pass context.Source: §2 · p. 2
- The field lacks an LLM-based end-to-end architecture-recovery solution for industrial codebases that is simultaneously semantics-aware, business-context-aware, and scalable.Source: §2 · p. 2
3. APPROACH
ArchAgent processes repositories through summarization, segmentation, repository-level synthesis, and diagram generation. Its approach uses adaptive grouping, structural references, related-file context, and cross-repository signals to support system-level views.
3. APPROACH
- The workflow segments repositories into LLM-compatible chunks, synthesizes an overview from summarized content and repository signals, then merges partial Mermaid diagrams.The overview uses API specifications and QPS metrics; Figure 1 presents the overall workflow.Source: §3 · p. 2, Figure 1 · p. 2
- Adaptive grouping partitions repository summaries into G = ⌈T/M⌉ groups, where T is total tokens and M is the model-input threshold.A depth-first file traversal uses 10% overlap between adjacent groups to limit intergroup correlation loss and avoid undersized tail groups.Source: §3 · pp. 2–3
- File summarization uses AST-derived file-, class-, and function-level reference graphs and identifies functionally related files before summarizing a target file.These references provide auxiliary context, while related-file identification is intended to improve awareness of interrelated responsibilities.Source: §3 · p. 3
- The pipeline aggregates cross-repository API usage, QPS, and repository documentation signals and incorporates them into model context.Source: §3 · p. 3
- The Readme Generator identifies entry points, traces downstream dependencies, and incorporates inter-repository interaction signals into a system-level README.The README highlights architecture, key modules, and execution flows.Source: §3 · p. 3
4. EVALUATION
The evaluation compares ArchAgent with DeepWiki on large repositories, tests the contribution of dependency context, and examines a production SQL-transformation codebase. Across these studies, it reports higher architecture-diagram F1, improvements from dependency context, and recovery of business-critical modules.
4.1. Scalability Evaluation
- The benchmark comprised eight production-grade GitHub projects with 1k–22k source files, evaluated against public architecture documentation.The projects span Go, Java, C/C++, Python, and YAML.Source: §4.1 · p. 3
- ArchAgent’s F1 was 0.966 (σ=0.025) versus DeepWiki’s 0.860 (σ=0.067) across repositories; the difference was significant (paired t-test p=0.0036).Figure 2 shows the F1-score distributions across repositories.Source: Figure 2 · p. 4, §4.1 · p. 4
4.2. Ablation Study on Contextual Dependency
- Dependency context increased contextual F1 by 0.11 for Qwen 3 and 0.07 for Llama 3; full-method performance did not significantly differ between models (p=0.361).Figure 3(a) summarizes the four conditions’ mean±SEM, while Figure 3(b) shows the per-model improvements.Source: §4.2 · p. 4, Figure 3 · p. 4
4.3. Case study
- In a 621-file Java SQL-transformation repository, the diagram surfaced the parsing, named-entity recognition, control/coordination, and SQL-conversion modules.The maintainer judged it to provide almost perfect coverage of information usually needed for communication.Source: §4.3 · pp. 4–5, Figure 4 · p. 5
- Although SQL conversion was implemented in one Java file, the diagram gave its workflow a dedicated, fine-grained subview.Class-level details were removed and concrete identifiers in the sql-convert module were replaced with anonymous numeric labels.Source: §4.3 · pp. 4–5
5. CONCLUSION
ArchAgent targets business-aligned architecture recovery from large-scale legacy systems. The conclusion highlights adaptive grouping and enhanced summarization as approaches to context-window and business-semantics limitations, alongside reported improvements over industrial baselines.
5. CONCLUSION
- ArchAgent targets recovery of business-aligned architecture from large-scale legacy software systems.The conclusion identifies adaptive grouping and enhanced summarization as ways to address LLM context-window and missing-business-semantics limitations.Source: §5 · p. 5
- The conclusion reports substantial improvements over industrial baselines and emphasizes dependency context’s role in capturing business logic.Source: §5 · p. 5
- The approach combines adaptive grouping with enhanced summarization for scalable and accurate architecture reconstruction.Source: §5 · p. 5