Legacy modernization playbook
Five routes out of an old system, the risk each one carries, and the order that keeps the business running while you move.
What the playbook covers
4 things that decide this
- 01The big rewrite is the most popular route and the one that fails most often, because it asks you to stop improving the business for a year.
- 02Replacing a legacy system one function at a time keeps the old one live while the new one earns its place. Every step is reversible.
- 03The hardest part is rarely the code. It is the rules nobody wrote down, which live only in what the current system does.
- 04Choose the route by what you cannot afford to break, not by which technology the team prefers.
The rewrite that never lands
A legacy system is one people are afraid to change. That fear is usually earned. Nobody remembers why a rule exists, the person who wrote it left, and the only specification is the running code.
Rebuilding it properly is the instinct. So a team spends a year on a replacement while the old system keeps taking orders and drifting further ahead. On switch day, both systems are wrong in different ways.
The alternative is less exciting and it works. Pick one function, build it new, route real traffic to it, and delete the old path once it is proven. Repeat. Go4Gr8 moved off a no-code tool this way, and the value was never the chatbot. It was the multi-tenant infrastructure underneath, which is what turned an idea into something sellable.
- Pick one functionThe riskiest one you can reverse
- Write the rules downObserved behaviour, not the docs
- Build beside itThe old path keeps serving
- Run bothCompare outputs on real traffic
- Switch the routeOne flag, reversible in seconds
- Delete the old pathUntil then, you own two systems
The last step is the one teams skip. Two live paths cost more than either alone.
Five routes, and what each one costs you
Cost here is risk and effort, not money. Pick by the row that matches what you cannot afford to break.
| Route | What it means | Choose it when | What it risks |
|---|---|---|---|
| Leave it | Freeze changes and keep it running | It works, nobody needs new features, and it is not blocking anything | Skills and dependencies age out from under you |
| Wrap it | Put an API in front and build new work against that | The data is right but the interface is the bottleneck | You are now maintaining the old system plus a layer |
| Re-platform | Move it, mostly as-is, onto current infrastructure | Hosting and support are the pain, not the design | Old design problems arrive intact at the new address |
| Replace function by function | Build new pieces beside the old and switch traffic gradually | The system is business-critical and cannot pause | Two systems live at once, so the migration must finish |
| Rewrite | Build the replacement whole, then switch | The system is small, or the business rules are genuinely known | A long gap where nothing improves, and both versions drift |
Recover the rules before you rebuild anything
Most modernization work fails on undocumented rules. A discount applies only to accounts opened before a certain date. An invoice rounds a particular way. Nobody remembers agreeing to either, and both are load-bearing for someone.
So the first deliverable is not architecture. It is a written record of what the current system actually does, recovered from its behaviour and confirmed by the people who depend on it.
Run the old and new paths side by side on real traffic and compare the outputs. Disagreements find the rules nobody could tell you. That comparison is worth more than any specification meeting, and it is the only method that discovers the rules nobody knew existed.
- 01Start with the function whose failure you could reverse fastest, not the easiest one.
- 02Keep the switch behind a flag so reverting takes seconds and needs no deploy.
- 03Budget for deleting the old path. A migration that never finishes doubles the maintenance.
- 04Write down each recovered rule as you find it, with the person who confirmed it.
