Program Comprehension and Structural Extraction in Legacy Reverse Engineering

Software maintenance and modernization initiatives frequently stall due to documentation decay. In enterprise environments, legacy codebases accumulated over decades often function as undocumented monoliths or distributed networks of microservices whose original design rationale, dependency hierarchies, and boundary contracts have been lost to personnel turnover. Reverse engineering these systems requires program comprehension—the cognitive process through which software engineers construct mental models of software topology, control flow, and semantic intent.

Historically, program comprehension relied on manual inspection augmented by deterministic static analysis (such as call graph generation) and dynamic profiling. The advent of large language models (LLMs) featuring context windows spanning hundreds of thousands to over one million tokens prompted a naive hypothesis: entire code repositories could be ingested monolithically into an extended context prompt to automatically generate accurate architecture diagrams, sequence topologies, and system documentation.

Empirical evaluation reveals that context window expansion does not equate to effective semantic comprehension. Monolithic repository ingestion suffers from severe attention dispersion, positional bias, and loss of structural precision across multi-hop code dependencies. Effective reverse engineering of undocumented software requires shifting from monolithic prompt-stuffing to staged neuro-symbolic extraction workflows. By coupling deterministic abstract syntax tree (AST) parsing with adaptive, multi-stage LLM synthesis, engineering teams can reliably extract system topology and translate fragmented source implementations into structured, verifiable architectural artifacts.

The Breakdown of Monolithic Context Ingestion

Monolithic prompt injection treats an entire codebase as a continuous, flat text stream. This approach fails to mirror the non-linear, hierarchical execution model of software systems. When source trees containing hundreds of thousands of tokens are supplied without structural pre-indexing, models demonstrate marked difficulty resolving long-range functional relationships, indirect interface implementations, and cross-module boundary contracts.

The primary failure mode is edge hallucination in generated visual artifacts, such as Mermaid or PlantUML diagrams. The model frequently fabricates direct coupling between distant modules where none exists, or omits intermediate message brokers, data access layers, and remote procedure call (RPC) contracts. This structural degradation occurs because transformer self-attention mechanisms, while capable of local lexical matching, experience diminished multi-hop reasoning over extended code sequences without explicit topological scaffolding.

Structural Decomposition and AST-Guided Staged Synthesis

To circumvent the fundamental limitations of monolithic ingestion, contemporary architectures decouple structural extraction from semantic synthesis. Rather than delegating dependency discovery to the generative model, deterministic static analysis tools extract the underlying topology prior to model intervention.

+-------------------------------------------------------------------+
|                  Undocumented Legacy Repository                   |
+-------------------------------------------------------------------+
                                  |
                                  v
+-------------------------------------------------------------------+
|                     Deterministic AST Parsing                     |
|  (Extract functions, classes, interfaces, entry points, & APIs)   |
+-------------------------------------------------------------------+
                                  |
                                  v
+-------------------------------------------------------------------+
|         Topological Clustering & Depth-First Search (DFS)         |
|         (Adaptive grouping under token budget + 10% overlap)      |
+-------------------------------------------------------------------+
                                  |
                                  v
+-------------------------------------------------------------------+
|                   Staged LLM Semantic Synthesis                   |
|        (Generate subsystem summaries & local Mermaid fragments)   |
+-------------------------------------------------------------------+
                                  |
                                  v
+-------------------------------------------------------------------+
|              Global Topology Reconciliation & Merge               |
|      (Reconcile cross-module edges into unified C4/Mermaid IR)    |
+-------------------------------------------------------------------+
                                  |
                                  v
+-------------------------------------------------------------------+
|                Bidirectional Verification Loop                    |
|    (Validate diagram nodes/edges against static call-graph AST)   |
+-------------------------------------------------------------------+

Deterministic Topology Extraction and Boundary Identification

The initial phase requires deterministic analysis via language-specific abstract syntax trees. Parsers traverse source code files to build an explicit symbol table and directional call graph:

1. Entity Extraction: Parsing file-, class-, interface-, and function-level declarations.
2. Boundary Identification: Identifying execution entry points (e.g., HTTP route declarations, message consumer listeners, CLI commands) and egress points (e.g., database drivers, outbound RPC clients, external SDKs).
3. Cross-Service Signatures: Extracting serialization formats, schema definitions (such as Protocol Buffers, OpenAPI specs, or SQL migration files), and network call patterns.

This static pass establishes a verifiable ground truth for system components and cross-file dependencies.

Adaptive Grouping and Subsystem Fragment Synthesis

Once the deterministic dependency graph is constructed, code fragments cannot simply be concatenated. An adaptive clustering strategy groups related files based on topological proximity. In specialized implementations like ArchAgent, repository summaries are adaptively partitioned to fit within constrained token budgets using Depth-First Search (DFS) traversal over the dependency tree [1]. Adjacent clusters maintain a calculated 10% token overlap to preserve interface semantics and functional continuity across grouping seams [1].

Each cluster is subsequently passed to an LLM alongside its static dependency metadata. Rather than requesting a global architecture diagram immediately, the model executes a localized role: generating module-level structural summaries and declarative diagram fragments (such as localized Mermaid subgraphs). In an evaluation across eight enterprise-grade code repositories ranging from 1,000 to approximately 22,000 files per project, this structured, AST-informed DFS approach demonstrated a mean F1 score of 0.966 for architectural representation accuracy, outperforming monolithic baseline systems such as DeepWiki (0.860) with high statistical significance (p = 0.0036) [1].

Methodological Comparison: Monolithic Ingestion Versus Agentic Workflows

Empirical research confirms that scaling context window capacity does not resolve repository-level reasoning challenges. The LongCodeBench benchmark evaluated frontier model performance across context lengths scaling up to one million tokens on code comprehension and repair benchmarks [3]. The findings documented significant capability drop-offs as context sizes increased: historically capable baselines like Claude 3.5 Sonnet saw performance drop from 29% to 3%, while models such as Qwen2.5 declined from 70.2% to 40% under maximum context loading [3].

These empirical observations invalidate the paradigm of raw code dumps for architecture generation. Reliable documentation synthesis necessitates modular, agentic workflows with integrated feedback mechanisms.

Multi-Stage Validation Loops for Architectural Decisions

Beyond generating static system diagrams, deciphering legacy architectures requires reconstructing the historical Architectural Decision Records (ADRs) that explain why specific patterns were chosen. The AgenticAKM architecture illustrates the efficacy of isolating extraction, retrieval, generation, and validation into distinct agentic stages [2].

In AgenticAKM, repository summaries and extracted candidate decisions are iteratively validated across up to three refinement cycles per stage [2]. In blind evaluations across 29 repositories containing between 1,000 and 350,000 lines of code, outputs generated via staged agentic refinement achieved aggregate quality scores of 3.8 to 3.9 out of 5, whereas single-prompt monolithic outputs scored 3.3 out of 5 [2]. Crucially, while this validation architecture markedly improves decision documentation, diagram accuracy requires an explicit verification step where generated nodes and edges are cross-referenced directly against AST call sites.

Multi-Model Routing in Production Infrastructure

In practical enterprise deployments, such as evaluations conducted by specialized research platform AI Plaza, engineers orchestrate heterogeneous frontier models across specialized roles rather than relying on a single static model. High-throughput, cost-efficient models such as Claude-Haiku-5.5 and DeepSeek-V4.1-Flash are assigned to initial AST parsing, module-level summarization, and local interface tagging.

Conversely, high-order topological reconciliation—such as resolving cross-module edge conflicts, merging Mermaid fragments into a unified C4 container model, and synthesizing system-wide ADRs—is routed to frontier reasoning engines like GPT-6.1 Sol, Claude-Sonnet-5.5, Gemini-4-Argon, or Grok-4.7. By decoupling parsing from high-level reasoning and applying multi-model routing to segmented intermediate representations, development teams avoid the performance cliffs documented in monolithic long-context evaluation [3].

Macro Architectural Trends in Automated System Archaeology

The transition away from raw, single-prompt code ingestion toward neuro-symbolic extraction signifies a maturation in automated software engineering. Several macro patterns are governing the modernization of legacy enterprise systems.

Neuro-Symbolic Compilers Replace Generative Guesswork

Purely generative approaches to software architecture documentation are increasingly viewed as insufficient for safety-critical and highly regulated enterprise systems. The emerging paradigm couples symbolic execution, compiler-based static analysis, and neural generation. Deterministic engines generate the system's skeleton—defining the rigid graph of packages, classes, foreign keys, and endpoint schemas—while long-context models populate the semantic flesh: synthesizing operational intent, detecting domain boundaries, explaining legacy business logic, and drafting architectural rationales.

+-------------------------------------------------------------------+
|                    Symbolic Deterministic Core                    |
|           - Compiler AST Parsing      - Call Graphs               |
|           - Schema Introspection      - Symbol Tables             |
+-------------------------------------------------------------------+
                                  |
                                  v
+-------------------------------------------------------------------+
|               Intermediate Representation Layer (IR)              |
|        Structured JSON Schema: Nodes, Edges, Signatures, Endpoints |
+-------------------------------------------------------------------+
                                  |
                                  v
+-------------------------------------------------------------------+
|                   Neural Generative Synthesis                     |
|           - Intent Explanation        - ADR Generation            |
|           - Mermaid / C4 Rendering    - Domain Mapping            |
+-------------------------------------------------------------------+

In this hybrid topology, the LLM functions not as a primary database of record, but as a compiler backend. The model transforms an intermediate representation (IR) of structured AST data into human-readable narrative and declarative diagrams.

Continuous Architecture Mining and Dynamic Living Documentation

Historically, legacy reverse engineering was treated as a one-time migration precursor. Once modernization finished, newly created documentation inevitably lapsed into obsolescence. Modern workflows integrate automated architectural reverse engineering directly into continuous integration and continuous deployment (CI/CD) pipelines.

Whenever a commit introduces modifications across module boundaries, automated pipelines extract updated AST subgraphs, synthesize modified sequence fragments, and update repository-level C4 diagrams stored directly as code (e.g., Mermaid.js or Structurizr definitions). Because generation is constrained to validated, staged diffs rather than full-repository reprocessing, execution costs remain minimal and structural integrity is consistently maintained.

The empirical literature confirms that context capacity cannot compensate for structural blindness. Resolving undocumented legacy architectures requires disciplined decomposition: deterministic structural extraction via ASTs, localized fragment synthesis over bounded token budgets, and iterative validation of diagram topologies against empirical source code references.

References

[1] https://arxiv.org/html/2601.13007 [2] https://arxiv.org/html/2602.04445 [3] https://arxiv.org/html/2505.07897v3