We Asked AI to Map Five Old Software Systems. Here Is What Architects Should Learn.
A plain-language guide to AI-assisted domain-driven design: The challenges, what we found, and seven takeaways.
Cover image
Most big companies run on old software. It still works. It still makes money. But few people know everything it does.
AI can now read code fast. So a tempting idea is spreading: "Let AI read the old system and rewrite it."
We wanted to test the first half of that idea. Can AI read an old system and explain the business inside it? And can we trust what it says?
To find out, we ran an open-source AI tool on five public codebases. This article shares what we learned, in plain words and pictures.
A few words first
Domain-Driven Design (DDD) is a way to build software around how the business works. The "domain" is the business area, such as billing, shipping, or claims.
A bounded context is one part of the business with its own words and rules. Inside it, each word has one clear meaning. "Order" in the kitchen can mean something different from "order" in billing. Good architects draw a line between those parts.
A monolith is one large program that does many jobs. A legacy system is old software that a business still depends on.
AI-assisted domain discovery means using AI to find those business parts inside existing code. The goal is a map, not new code.
Why this is hard
Code tells you what a system does. It rarely tells you why. A rule that looks strange could be a bug. It could also be a promise the company made to a big customer 20 years ago. The code alone cannot tell you which one it is.
That gap is the first challenge. We kept four traps in mind while we tested.
Trap 1: Names can lie. A folder called "billing" can hold almost no billing logic. Classic code-analysis tools draw a map of which code calls which. That map groups code by technical layers, not by business meaning.
Trap 2: AI agrees too easily. An AI model that sees a package named "pathfinder" may decide it is its own business area. It may not check whether the code inside is real or a placeholder.
Trap 3: Copying copies the bugs. If a rewrite matches the old system line by line, it also keeps the old mistakes. Nobody notices until the new system goes live.
Trap 4: A business area is not a microservice. A microservice is a small program that a team deploys on its own. A clear business boundary does not mean you need one. You can keep one well-organized program with clean internal parts, called a modular monolith. Splitting it up is a separate decision.
What we tested
We used Han, an open-source add-on for Claude Code, Anthropic's AI coding tool. Han's /ddd-analysis skill reads a codebase and builds a map of business areas, with evidence for each claim. It does not change code, and it does not recommend how to split a system into services.
Figure 1. How Han works: investigate, draft, challenge, and fix.
Han works like a small team of investigators. Five AI agents read the code at the same time. Each one looks for one kind of clue: Business words, business capabilities, who owns which data, how the code is built, and how it behaves when things go wrong.
Next, a modeler agent turns those clues into a draft map. Then a critic agent attacks the draft. It checks each proposed business area against the evidence. Last, the modeler fixes the draft one time. (Han documentation)
Han rates each business area at one of three levels:
- CURRENT: The code already shows this area clearly.
- LATENT: The area is real, but it is tangled with another one.
- SPECULATIVE: The evidence is thin. A business expert must decide.
We ran Han version 1.0.0 on five public systems. We used its smallest and cheapest depth setting.
Figure 2. Five systems that architects already know — and the critic's verdict on each candidate area.
- AWS CardDemo is a credit card system written in COBOL, an older language used on mainframes. AWS built it to show mainframe migration.
- The FTGO monolith is a food delivery app. Chris Richardson uses it in his book Microservices Patterns to teach how to split a monolith.
- The Citerus DDD Sample is a cargo shipping app based on Eric Evans's original DDD book.
- eShopOnWeb is Microsoft's sample online store.
- MyBatis JPetStore 6 is a classic Java web store for pets.
All five runs together cost about $31 in AI usage. Each run took 13 to 46 minutes.
Finding 1: The AI gave a short list, not a pile of services
Figure 3. Two labels to read separately: boundary tiers and critic verdicts.
Han's investigators logged 186 clues across the five systems. That is 33 to 49 clues per system. From those clues, the modeler proposed 16 business areas. After the critic's review, 14 remained.
Han rated 11 of the 14 as CURRENT, 1 as LATENT, and 2 as SPECULATIVE. That works out to two to four business areas per system. Han never suggested breaking a system into dozens of microservices.
The old COBOL system was not harder for Han than the Java and .NET ones. In CardDemo, Han separated the card account ledger, purchase approvals, and operator sign-on. It also found four different programs that change the account balance. That is a warning sign for anyone planning a rewrite.
Finding 2: The critic changed the answer
Figure 4. A second AI, the critic, changed three of the five answers.
The critic was the most useful step. It changed the map in three of the five systems:
- CardDemo: It folded "Cardholder and Card Portfolio" into another area.
- FTGO: It folded in "Restaurant Menu Catalog." The critic noted that the code has no way to change a menu over time.
- DDD Sample: It marked "Transport Route Finding" as a weak guess. The code that plans routes is a stand-in that returns random routes.
Across all 16 proposed areas, the critic gave 4 Strong, 9 Plausible, 3 Weak, and 0 Reject verdicts.
Zero rejections matters. The critic marks weak ideas as weak instead of deleting them. That keeps them visible, which is good. But it also means you must read the verdicts, not only look at the map.
The DDD Sample shows why. In the book, route finding belongs to a different team. The code comments say so too. Han saw those comments. But it wanted proof in the code itself and did not find it. So it asked a question instead:
"Does the routing team's 'route' mean the same thing as the booking team's itinerary?"
That is the right question to bring to a business expert.
Finding 3: Code shows today, not tomorrow
Figure 5. FTGO's published design compared with what the code supports today.
FTGO is a useful test because its target design is public. Richardson's book splits it into six services: Order, Kitchen, Delivery, Restaurant, Consumer, and Accounting.
Han found one clear area, the order lifecycle. It found one tangled area, courier delivery. It treated the kitchen, restaurant, and consumer logic as parts of the order. It found no accounting logic beyond a payment class and a to-do note.
That is not a failure. It is an accurate reading of the code. Richardson himself writes that the monolith's Order class represents both orders and deliveries. Han labeled that same tangle as LATENT.
The code shows where the business is today. Only people can decide where it should go next.
Finding 4: The real treasure is hidden rules
Figure 6. Four hidden rules a rewrite would copy without anyone noticing.
The most useful output was not the map. It was a list of odd rules that a rewrite would copy without anyone noticing. Han flagged rules like these in all five systems. We checked four of them by hand against the source code. All four held up.
CardDemo. Each approved purchase adds to a "credit balance" field. No program ever subtracts from it.
FTGO. The order-minimum check is backwards. It throws an error when the new total meets the minimum. The default minimum is set so high that the check almost never runs, which hides the problem today.
JPetStore. Checkout lowers the stock count with no floor. Inventory can drop below zero.
eShopOnWeb. There are two ways to edit a product. One changes 2 fields. The other changes 5.
Figure 7. Han’s context map for CardDemo: three business areas and the seams between them.
CardDemo shows why this matters. Three programs touch the card's credit data. The approval program adds each purchase to the credit balance. The nightly posting job updates the main account file, but it never touches that balance. The cleanup job deletes old approvals, but it never saves the lower totals back. If nothing else resets the balance, available credit only shrinks.
So is it a bug? Or does "credit balance" mean "approved but not yet posted"? Han asked that question. Only the business can answer it.
Han also flagged risks we did not check by hand. In CardDemo, money-moving updates span several files without an all-or-nothing safety step. In eShopOnWeb, checkout makes three separate saves with no transaction to tie them together. If the second save fails, the data is left half-done.
The most valuable output of AI discovery is a list of good questions for the business.
What the experts are saying
Our results line up with talks from DDD Europe 2026, held in Antwerp in June.
Eric Evans, who wrote the book that defined DDD, showed an experimental tool that compares business words across codebases. He presented its results as evidence for or against an idea, not as proof that a boundary exists.
In a conference interview, Martin Fowler described an AI "harness." It has guides that steer the work and sensors that check the results. He prefers plain, rule-based checks wherever they can do the job.
Fowler and Evans also said the real bottleneck is communication between developers and business experts. That stays true even when AI writes code faster.
Chelsea Troy applied the same bounded-context idea to AI chats. She separates exploring, brainstorming, deciding, and implementing, with clear boundaries between them.
Seven takeaways for architects
1. Ask AI to explain before you ask it to rewrite. Make a map first. A rewrite built on a wrong map moves faster in the wrong direction.
2. Treat every AI-drawn boundary as a guess with evidence. Facts come from parsers, dependency graphs, database schemas, and tests. Explanations come from the AI. Keep the two apart.
3. Use a critic step, then read its verdicts. In our test, the critic caught overreach in three of five systems. But the critic is also AI. Two AI agents agreeing is not proof.
4. Check the top evidence yourself. Open the files behind the three most important findings. Your own check is the only check that is not AI.
5. Hunt for hidden rules, then ask the business. For each odd rule, decide: Keep it, fix it, or drop it. Then write tests that lock in that decision.
6. Keep business boundaries separate from deployment choices. A clear boundary can live inside a modular monolith. Split into services only when a part needs its own team, release schedule, or scale.
7. Put limits on the agents. We gave Han read-only tools and its own output folder. The agents hit 2 to 12 blocked commands per run and found other ways to finish. That is a fair trade when AI reads code you did not write.
Try it on one system
Here is how we would start on a real system. This is our suggestion, not a measured result.
1. Pick one business capability. Choose billing, cancellations, or claims intake. Pick an area your experienced engineers and business experts know well enough to challenge.
2. Ask one clear question. For example: "Do billing and shipping use the word 'order' the same way?" Then run the tool on that area.
/han-ddd:ddd-analysis src/billing
/han-ddd:ddd-analysis small
3. Check the evidence. Look for missing workflows, rules with no support, and technical folders mislabeled as business areas.
4. Meet the business experts. Bring Han's questions. Write down every place where the code, the AI, and the business disagree.
5. Decide on changes separately. Only then choose to reorganize, extract a service, or leave the area alone. Write behavior tests and a plan for retiring old code before anyone writes new code.
What this test does not prove
We want to be clear about the limits. We used Han's smallest depth setting. Five public sample systems are smaller and cleaner than real enterprise code. The counts in this article describe what Han produced. They do not measure how accurate it is. Apart from FTGO's published design, we had no answer key.
Three of the runs also had to restart after the connection dropped. Han saves its work after every step, so each run picked up where it stopped.
The bottom line
AI does not remove the hard part of modernization. It moves it.
Reading old code is now fast and cheap. Deciding what the business meant is still slow, human work. Now it is the most important work on the project.
Here is a simple test for any AI-drawn map. Can your team trace each claim back to the code, challenge it, and explain why a change follows from it? If yes, you have input for a real decision. If no, you have a nice-looking diagram.
What evidence would your team need before trusting a boundary drawn by AI?
Further reading: the formal verification report behind this article, with the full ground-truth tables and critic verdicts: AI-Assisted Domain-Driven Discovery: Multi-Agent Synthesis and Adversarial Critique (PDF).
#DomainDrivenDesign #SoftwareArchitecture #LegacyModernization #GenerativeAI #Mainframe
Comments
Post a Comment