How We Used LLMs to Understand and Modernize a Legacy Delphi Application

Many legacy modernization projects start with a simple question: what does this thing actually do?

In this project, we were modernizing a decades-old Delphi application with limited documentation, no meaningful test coverage, engineers long since moved on, and significant unknowns about the environment in which it operated.

Modernizing legacy systems is challenging, particularly when documentation is limited and system knowledge has been lost over time. When LLMs and AI are applied thoughtfully, they can help teams understand legacy systems faster and reduce modernization risk.

This article focuses on how we used LLMs to understand, document, and de-risk an unfamiliar legacy system before modernization began. Once the application was understood and the architecture was defined, the team leveraged AI-assisted development workflows to accelerate the Delphi-to-.NET rewrite itself. Evan Sanning shares that side of the project in his companion article, How We Used LLMs to Rewrite a Legacy Delphi Application in C#.

Understanding an Unknown Legacy Application

Many legacy application modernization projects begin long before a single line of code is rewritten. They begin with understanding what the existing system actually does.

We’ve seen this pattern across clients: a business-critical application that nobody fully understands anymore. No architecture docs. No acceptance criteria. No real test environment. Much of the original system knowledge had been lost over time, leaving the application as something of a black box.

In this case, we inherited a legacy Delphi application with all of those challenges, and one more hidden surprise:

Manual code review revealed the dev and QA environments were pointed directly at production third-party commercial servers. One wrong move in testing, and real systems would feel it.

This is the modernization risk most teams underestimate. It’s not the rewrite itself. It’s navigating everything you don’t know before the first line of new code is written.

Applying AI Fluency 4D Framework to Legacy Application Modernization

AI fluency is a discipline, and successful legacy application modernization requires more than AI tooling. It requires a disciplined approach to applying AI within an engineering process.

We used Anthropic’s 4D framework to guide our modernization effort. We applied its four practices Delegation, Description, Discernment, and Diligence, and our efforts turned a legacy codebase into a delivered .NET application in half the projected timeline.

Delegation

Deciding what AI should do and what still requires human expertise.

We identified where AI could accelerate us:

• generating documentation,
• iterating on code, and
• exploring requirements.

And we identified where human judgment was irreplaceable:

• defining the architecture,
• evaluating risk, and
• making environment decisions.

That boundary didn’t blur. The engineer led. The LLM executed. The roles were set.

Description

Creating documentation for a legacy application is often one of the most time-consuming parts of a modernization project, which makes communicating clearly with AI systems especially important.

Before a single line of .NET was written, we fed the Delphi codebase to a large language model with clear, structured prompts and got back Markdown documentation covering entry points, key workflows, and data flows. We iterated with the LLM to refine how that information was organized and presented.

In many legacy systems, the source code has effectively become the documentation. Business rules, operational assumptions, and years of incremental decisions are often embedded directly in the implementation. One of the biggest advantages of using LLMs during modernization was the ability to surface and organize that knowledge much more quickly than traditional manual analysis.

What would traditionally have required days or weeks of manual investigation was compressed into a much shorter discovery process. Entry points, key workflows, data flows — captured in hours, not weeks.

The value wasn’t simply speed. By generating documentation, diagrams, and summaries early, the team could spend more time evaluating architecture and risk rather than manually tracing code paths. The goal was not to replace discovery work, but to spend more of that effort on higher-value engineering decisions.

This gave the whole team a shared mental model and created an artifact that will serve future engineers and AI agents alike. The documentation could be fed back to the LLM once we got to the execution of doing the rewrite. This documentation became the foundation for the broader legacy application modernization effort and helped reduce uncertainty before implementation began.

Discernment

Evaluating AI outputs with engineering judgment.

The LLM told us what the system did. The engineer determined how it should be rebuilt and what the LLM couldn’t see.

One lesson from this project was that documentation and understanding are not the same thing. The LLM was effective at explaining how the system behaved. Determining which behaviors were intentional, which were accidental, and which should be carried forward into the new architecture still required engineering judgment.

Manual code review of config files revealed that the non-production environments were pointing directly at production third-party commercial servers. This discovery immediately changed how we approached testing and validation.

That same critical review surfaced a missing failback mechanism: if a job failed, it failed permanently with no retry capability. The rewrite introduced retry and recovery mechanisms from the start.

We also found a tangle of hardcoded values that made environment portability difficult. It was often unclear which settings belonged in configuration files and which were buried directly in code. During the modernization effort, we made these values fully configurable across environments, simplifying deployments and reducing operational risk.

Documentation alone doesn’t make decisions. A senior engineer reviewed the LLM output, applied judgment, and defined the new .NET architecture. This architecture-first approach is critical in large-scale legacy software modernization efforts.

Once the architecture was clear, LLMs dramatically sped up iteration on requirements, component design, and code generation. Engineer the architecture, then accelerate with AI.

Diligence

Interacting with AI responsibly also meant validating our assumptions safely.

Knowing that testing against live production services was off the table, we built a mock of the third-party commercial service. This let us run the legacy Delphi app and the new .NET app side by side comparing outputs safely, without touching anything real.

The mock service also gave us a reliable, low-risk way to verify like-for-like behavior throughout the rewrite while reducing the risk associated with unknown production dependencies.

We were also intentional about what information was exposed to the LLM, ensuring that sensitive configuration data remained outside the model’s context.

What We Found Along the Way

Documenting the architecture didn’t just illuminate the existing system — it exposed its gaps. The legacy Delphi application had no failback logic. If a unit of work failed, it failed permanently. We built a retry and backup service into the .NET replacement from the start.

Beyond improving the application itself, documenting the architecture revealed an opportunity across the broader project landscape. Several applications shared common functionality that could be extracted into a reusable component. We packaged that functionality into a shared NuGet package, reducing technical debt and accelerating future modernization efforts.

Beyond accelerating delivery, the modernization effort improved reliability, configuration management, testability, and long-term maintainability. The project also produced reusable components and documentation that can support future modernization initiatives.

Result: A legacy application modernization effort originally estimated at five months was completed in approximately two and a half months while improving reliability, configuration management, testability, and long-term maintainability.

Once the architecture was established and the system behavior was understood, the team leveraged AI-assisted development workflows to accelerate the implementation itself. Evan Sanning covers that portion of the project in his companion article, How We Used LLMs to Rewrite a Legacy Delphi Application in C#.

AI Is the Accelerator. Judgment Is the Engine.

LLMs are extraordinary tools for documenting the unknown, generating boilerplate, and accelerating iteration. But throughout this project, the most important decisions were still made by engineers.

The LLM helped us understand the application faster. It helped us generate documentation, identify workflows, and accelerate implementation. But it didn’t replace the engineer who recognized that dev is hitting prod, who decided where the failback belongs in the architecture, or who identified opportunities to create reusable components across projects. Those decisions still required experience, context, and engineering judgment.

The teams that get the most from AI-assisted modernization aren’t the ones who hand the LLM the problem. They’re the ones who use it to move faster on decisions they’ve already made well.

In our case of Delphi modernization, the combination of AI-assisted discovery and experienced engineering judgment transformed a largely undocumented legacy application into a modernized platform delivered in approximately half the projected timeline.

Many organizations delay modernization because understanding the legacy system feels overwhelming. Our experience has shown that AI-assisted discovery, combined with experienced engineering oversight, can dramatically reduce uncertainty and accelerate the path forward.

If you’re planning a legacy application modernization initiative or struggling to understand an aging software platform, Keyhole Software can help you reduce risk, accelerate delivery, and build a sustainable modernization roadmap. (keyholesoftware.com/contact).