Software architecture · Level 6: Governance and evolution · Module 30 of 46

Migration, refactoring and roadmaps

Sooner or later an architecture needs to change shape: a monolith that can't scale its checkout, a legacy system nobody can safely modify. The temptation is the big rewrite. It rarely ends well. This module covers how to justify architecture work in business terms, the incremental migration patterns that work, the "elephant migration" antipattern, and how to plan the journey as a roadmap.

1. The idea

Renovating a hotel that stays open. You can't close it for two years and rebuild: guests would go elsewhere and never come back. Instead you renovate one floor at a time, moving guests between floors, so the hotel earns money throughout. Each floor finished is a visible improvement; if plans change halfway, the floors already done still count.

Justify it in business terms

"The code is messy" doesn't get budget. Connect the architecture problem to what the business cares about:

Time to market: "a typical feature takes six weeks; after splitting checkout, it would take two".
User satisfaction: "the site slows to 4 seconds every sale; that's when we lose most orders".
Cost and risk: "every release needs a weekend and three teams; one in five fails".
Strategy: "we can't launch in Germany until customer data can stay in the EU".

Migrate or adapt, and how

Approach	How it works	When
Adapt	Improve the existing system in place: modularise, add tests, fix hotspots (Module 29)	The shape is right, the code isn't
Strangler fig	Put a routing layer in front; move one capability at a time to the new system; the old one shrinks until it can be switched off	The shape is wrong; the system must keep running
Branch by abstraction	Inside the code, put an interface in front of the part to replace, build the new implementation behind it, switch over, delete the old	Replacing an internal component without a long-lived branch
Parallel run	Run old and new side by side on the same inputs and compare results before trusting the new one	High-stakes calculations (pricing, payroll, risk)
Big bang	Build the replacement completely, then switch over in one go	Small systems, or when nothing else is possible

Elephant migration is the antipattern of trying to migrate everything at once: "eating the elephant in one bite". Months of work with nothing in production, while the old system keeps changing underneath.

2. How it works

A strangler fig migration

A shop's monolith is replaced capability by capability, while customers keep shopping.

The elephant migration

The same goal, attempted as one big rewrite. Watch the months go by.

3. Try it yourself

Build a migration roadmap

Six migration projects compete for a team that can do about two each quarter. Rate each one's business value and risk reduction, and the roadmap orders them by (value + risk reduction) ÷ effort, respecting dependencies.

4. Trade-offs

Incremental vs clean slate

Incremental migration delivers value early and limits risk, at the cost of running two systems and a routing layer for a while. A rewrite avoids the dual running and bets everything on one late delivery.

Migrate vs adapt

Adapting is cheaper if the structure is basically sound. Migrating is necessary when the structure itself prevents a characteristic the business needs (Module 17).

Value first vs foundations first

Delivering the most valuable piece first builds support; some foundations (a routing layer, observability, a deployment pipeline) must come first anyway. Do the minimum foundation, then value.

Plan vs adapt the plan

A roadmap is a hypothesis. Revisit it each quarter as you learn what migration really costs and what the business needs next.

5. In real projects

Three ways to shape a roadmap. An iteration view groups projects into quarters or increments. A portfolio view shows every project and how they depend on each other. A priority view ranks them by value, risk reduction and effort. Most architects keep all three: priority to decide, portfolio to sequence, iteration to communicate.

Pick the first slice carefully. It should be valuable, fairly self-contained, and teach you the migration's real costs: routing, data sync, monitoring. Avoid the most tangled part first, and avoid something so trivial it teaches nothing.

Data is the hard part. Moving code is easier than moving data with live writes. Plan data ownership and synchronisation (Module 23) for every slice.

Say it in the interview

Two-sentence answers

"How would you migrate a monolith?" Incrementally, with a strangler fig: a routing layer in front, then one capability at a time to the new system, starting with a valuable, fairly isolated one. The old system keeps working until the last piece moves.
"How do you justify architecture work?" In business terms: time to market, user experience, cost and risk, or a strategic goal it unblocks, with numbers.
"Why not rewrite from scratch?" A rewrite delivers nothing until it's finished, chases a moving target and usually takes far longer than planned. Incremental migration delivers value and learning along the way.

Red flags interviewers notice

"We'll rewrite it in 6 months."
A migration plan with no first slice to production within a quarter.
Ignoring how data moves.

6. Remember it

Memory hook: "One floor at a time, hotel stays open"Migrate in slices behind a routing layer, each slice in production before the next begins.

How this hook works: what "one floor at a time" means

What the slogan means, phrase by phrase

"One floor at a time": Small, complete slices: one capability migrated and live before the next.
"hotel stays open": The business keeps running and earning throughout; nothing waits for a big switch-over.

Why this picture fits: everyone understands why you wouldn't close a busy hotel for two years, yet software teams propose exactly that.

The story → the concept

Renovating a hotel	Migrating a system
Reception redirects guests	The routing layer
One renovated floor	One migrated capability
Closing the old wing	Switching off the legacy part
Closing the whole hotel	The elephant migration

The trap it saves you from

The rewrite that's always six months from done.

7. Common mistakes

The elephant migrationMigrating everything at once. Nothing reaches production for a year, and the old system keeps changing.

Technical justification only"Better code" doesn't compete with features for budget. Translate into time, money, risk and strategy.

Forgetting to finishMigrations that stall at 80% leave two systems to run forever. Plan and fund the last slice and the switch-off.

Copying the old designRebuilding the old structure in new technology keeps the old problems. Migrate towards the target architecture, slice by slice.

8. Design exercise (30 minutes)

Write the business case (10 min). For one architecture problem you know, write three sentences connecting it to time, money, risk or strategy, with numbers.
Choose the first slice (10 min). If you strangled that system, which capability would move first, and why?
Draft the roadmap (10 min). Four quarters, two projects each, with dependencies. Which quarter switches the old system off?

9. Self-check quiz

How does a strangler fig migration work?

The old system shrinks slice by slice until it can be switched off.

What is the elephant migration antipattern?

Eating the elephant in one bite: no value until the end, and a moving target.

Which justification is most likely to win budget?

Cost and risk, with numbers, in business terms.

What is a parallel run?

Trust in the new system is earned before it takes over.

What makes a good first slice?

Early value and early learning, without the hardest problems first.

10. Go deeper

Resource	Time	Why
Strangler Fig Application (Martin Fowler)	10 min	The pattern and where its name comes from.
Branch By Abstraction (Martin Fowler)	10 min	Replacing a component inside one codebase without a long-lived branch.
Monolith to Microservices (Sam Newman)	book	Migration patterns, including data, in depth.