Why Kartographing Your Legacy System is the Best Investment You'll Ever Make

Skipping it will cost you 10x later

December 21, 2025 12 min read Legacy Modernization By Martin Dilger

Last week, I took the train from Seeon where my company is located to Hannover for an event modeling workshop.

Like every trip I take, I planned every single step. I know exactly which trains to take, where the connections happen, when I need to leave to have enough buffer in case something goes wrong. And I print it all out on one sheet of paper - intentionally going analog in case my phone dies or I lose signal.

It’s my map. My kartograph of the journey.

Here’s what hit me during that trip: Instead of planning the trip, most companies just stare at “their” Hannover and start the journey with hope and good intentions.

They focus on Hannover - the bright, shiny new system - without understanding where they’re actually starting from.

My company is near Munich. I can’t just look at Hannover and start walking. I need to know how to get to Munich, how to get from Munich to Hannover, how to get from Hannover Hauptbahnhof to the hotel, how to get from the hotel to the workshop location.

Each leg matters. Miss one connection, and you’re stranded.

The Problem: Legacy Systems Are Historical Records, Not Documentation

Every legacy system is full of decisions that were made because someone had a problem in production. Because someone from business needed the system to do a certain thing in a certain way. Because there was a fire, and someone put it out with whatever tools they had.

Your legacy system isn’t just code. It’s a historical record of every compromise, every patch, every “we’ll fix this properly later” that never got fixed properly.

And most modernization projects ignore this completely.

They start with a rough idea of what the system does. They focus on the destination - microservices, event-driven architecture, cloud-native infrastructure - without ever mapping where they’re starting from.

It’s doomed to fail.

You’ll end up exactly where you started in a few years, wasting massive amounts of money. Because all those missing requirements - all those hidden business rules buried in 3000+ commits - will end up as the same hacks and if/else statements that killed your current codebase.

You’re not modernizing. You’re just recreating the same mess in newer technology.

The Kartographing Approach: Three Phases of Zooming In

Last week in Hannover, we spent one hour on an existing system and used AI to build an event model from it.

We work in phases. Each phase zooms in deeper.

Phase 1: The Zoomed-Out Map (30-60 minutes)

First, we do a high-level analysis. We want to understand the contexts we have - the major domains and how they relate to each other.

This is the big picture. The 30,000-foot view.

AI can identify what happens from the code - it can see the pieces. But it can’t properly identify the relationships between contexts, and it definitely can’t figure out the timeline - what happens in which order.

So we bring in the human expert. We correct the high-level analysis. We sketch the proper sequencing. We give feedback to the AI.

After this phase, we have our first map: the contexts and their relationships to each other, with timing that actually makes sense.

Phase 2: Pick Your Chapter (30-60 minutes)

Now we zoom in. We pick one use case - one workflow - and go into more detail.

AI builds the timeline again, but this time it’s looking at API endpoints, persistence layers, and unit tests. It’s building Given/When/Then scenarios based on actual code artifacts.

In Hannover, we went through the map the AI built. Most of it was correct. Again we would bring back the human into the loop - sketching missing details, correcting minor things, handing it back to the AI.

Phase 3: Go Deeper, Chapter by Chapter (Iterative)

Then we do another round of detailed analysis. Going deeper and deeper into each workflow.

A chapter is just a part of a process. We go chapter by chapter.

First, you get the contexts - for my famous e-commerce example like cart, checkout, acquisition. Then we pick “cart” to zoom in. We identify chapters like stock check, product selection, price calculation.

Then we zoom into “product selection.” We identify product configuration, product upgrade, product details.

More and more, getting into the details. Like Russian dolls - each layer revealing more specific workflows within workflows.

The Given/When/Thens give us a clear picture of what’s going on.

In Hannover, it took about half an hour to identify some critical business rules.

I did not have to read a single line of code.

You can go extremely fast with this. And the good thing - using event modeling, we can use the knowledge of business experts and engineers together. It’s visual. It’s collaborative. It’s a universal language.

The System We Analyzed Had More Than 3000 Commits

Think about that for a second.

3000+ commits. This project started in 2019 - It was 6 years of accumulated decisions, patches, business logic changes.

Just checking out the codebase and trying to get a first impression would have taken longer than our entire kartographing session.

Traditional code archaeology - reading through thousands of lines, interviewing people who may or may not remember why something was built that way, digging through old documentation that may or may not exist - would take weeks. Maybe months.

And you’d still miss things.

The “Map” you are building is typically scattered across dozens of places.. some is in Jira, some lost in Confluence… some is documented in README.md and a lot in the heads of different people.. in fact, you start your journey without a map.

The 10x ROI (Or More)

If you ask me, kartographing your legacy is about the best investment a company can make.

Every minute spent mapping the legacy will pay 10x the rent later. Probably much more.

Here’s why: You’re buying insurance against building the wrong thing.

When you skip the kartographing phase and start modernizing based on your “rough idea” of what the system does, you will discover missing requirements. Not in week one. Not in month one.

You’ll discover them in month six. Or month twelve. Deep into the modernization project, when fixing them costs 10x - or 100x - what it would have cost to find them up front.

You’ll discover a business rule that someone added five years ago because a major customer needed it. Nobody documented it. It’s buried in an if/else block somewhere. The person who wrote it left the company three years ago.

And now you’ve built your shiny new microservice without it. And production breaks. And you’re scrambling to patch it. And that patch becomes the next hack that kills your codebase in three years.

Every patch is a crack in your fundament. Put in enough cracks and your team will start talking about the “necessary rewrite”.

Without the map, you’re not modernizing. You’re just moving the mess around.

The Brutal Truth About Modernization

You cannot just look at Hannover.

You need to know how to get to Munich first. Then Munich to Hannover. Then Hannover station to the hotel. Then the hotel to the workshop location.

Each leg of the journey matters.

Most companies skip the first leg entirely. They don’t even know where they’re starting from. They just know they want to get to “the cloud” or “microservices” or “event-driven architecture.”

So they start walking in what they think is the right direction.

And six months later, they’re lost. They’ve spent hundreds of thousands of euros - maybe millions - and they’re no closer to Hannover than when they started. In fact, they might be further away.

Because they never kartographed where they were starting from.

Before You Start Your Next Modernization Project

Kartograph your legacy.

Understand where you’re starting from. Map every context. Map every chapter. Surface every hidden business rule.

Use AI to accelerate the process. But bring the human expert into the loop to correct the timing, validate the relationships, and catch what the AI can’t see.

Go phase by phase. Zoom in layer by layer. From contexts to chapters to workflows to specific business logic.

Get business experts and engineers in the same room, looking at the same visual model, speaking the same language.

Spend the hours - or days - up front to build the map.

Then - and only then - start building toward Hannover.

Because every minute you spend kartographing will pay 10x in avoided rework, prevented fires, and eliminated waste.

It’s the best investment you’ll ever make.

And skipping it? That’s the most expensive mistake you’ll ever make.

I Will Help You With This

In my Workshop we´ll combine AI, Event Modeling and expertise from your Team to build the map. That´s your starting point for the modernization journey - like my plan printed on a sheet of paper - just that we use an Event Model.

Join the Agentic Engineer Program

Apply Spec-Driven Development Hands-On - Event Modeling, Event Sourcing, and AI Engineering with autonomous agents.

Learn More →

Book a Call Today

Want to talk through how Event Modeling could work for your team or project? Let’s have a quick, no-pressure conversation.

Book a Call Today →