Rebuilding Legacy Software: A Step-by-Step Guide
Legacy software rarely announces itself as a problem. It announces itself as a slowdown. A feature that should take a week takes three. A bug fix in one module breaks something unrelated in another. Onboarding a new developer takes months instead of weeks because the system is only fully understood by one or two people who've been living with it for years.
By the time a business decides the legacy system needs replacing, the problem is usually significant. The question is never whether to modernise — it's how to do it without destroying business continuity in the process.
The "how" is where most modernisation projects fail. A full rewrite launched in parallel with the existing system, intended to replace it on a specific date, is one of the highest-risk activities in software engineering. It consistently takes longer than estimated, costs more than budgeted, and frequently fails to replicate business-critical edge cases that were buried in the original system. The legacy system stays on life support while the new one catches up, sometimes indefinitely.
There is a better approach. It's incremental, risk-bounded, and keeps the business running at every step.
Rewrite vs. Refactor: The First Decision
Before planning any modernisation effort, the first question is whether the system needs to be rebuilt or restructured. The answer determines everything that follows.
Refactoring improves the internal structure of existing code without changing its external behaviour. It's the right choice when the core business logic is sound but the code is brittle, poorly organised, or hard to extend. Refactoring allows you to modernise incrementally — improving test coverage, extracting clean modules, replacing outdated dependencies — while the system continues to serve users. Each change is small, testable, and reversible.
Rewriting replaces the system from scratch. It is rarely the right first choice and should be reserved for situations where the existing architecture genuinely cannot support what the business needs — the underlying stack is technically obsolete, compliance requirements can't be met through patching, or the structural design is so fundamentally wrong that refactoring would amount to replacing every line of code anyway.
The statistics on full rewrites are sobering. [VERIFY: industry sources frequently cite 60–80% of full software rewrites failing to deliver expected value, often exceeding budget and timeline significantly — verify specific figures before quoting to clients]
The practical test: can you identify specific, bounded areas of the system where modernisation would deliver clear value? If yes, start there — that's a refactor path. If the answer is "we'd have to change everything to fix anything," you may have a rewrite candidate, but even then, the incremental approach produces better outcomes than a big-bang replacement.
The Most Dangerous Mistake: The Big-Bang Rewrite
The big-bang rewrite follows a predictable pattern. The team decides the existing system is too broken to fix. A new system is built in parallel over an estimated timeline. The estimated timeline passes. The new system isn't ready. The old system continues in production, accumulating bug fixes and new features that don't exist in the new one. The new system eventually launches — late, over budget, missing edge cases — and the cutover creates incidents that the old system never had.
The fundamental problem is that legacy systems accumulate years of institutional knowledge in the form of edge case handling. Every time a bug was fixed, a special case was added. Every time a business rule changed, the code was patched. This knowledge is embedded in the code, not in documentation. A ground-up rewrite that treats the legacy system as something to be discarded rather than a source of business logic specifications will miss this knowledge systematically.
The better framing: the legacy system is the specification. Every behaviour it exhibits — including the undocumented ones — represents a business requirement that the replacement must handle. Treating it as the ground truth, rather than the obstacle, produces far better outcomes.
The Strangler Fig Pattern: How to Modernise Without a Big Bang
The Strangler Fig pattern — named after a tropical vine that gradually grows around a tree without killing it until the vine can stand on its own — is the industry-standard approach to legacy modernisation. It works by replacing functionality incrementally while the old system continues to serve production traffic.
The mechanics:
Step 1: Place a routing layer in front of the legacy system.
Before touching any legacy code, introduce a façade or API gateway that sits between users (or client applications) and the legacy system. Initially it passes all requests through unchanged. Its purpose is to give you control over where traffic goes — so that you can route individual features to new services without changing the client.
Step 2: Identify the first module to extract.
Choose the extraction target carefully. The best first candidates share these properties: they are relatively self-contained (minimal dependencies on other parts of the legacy system), they have high maintenance cost or business value, and they are understandable enough to be replicated confidently. The goal is a quick, successful first extraction that builds confidence in the process.
Step 3: Build the replacement module.
Build the replacement as a standalone modern service — with its own database, its own test suite, its own deployment pipeline. Don't reuse legacy code; rebuild the functionality cleanly in the modern stack.
Step 4: Run both in parallel briefly, then switch.
For a brief parallel period, both the legacy module and the new service are active. Some teams run comparison tests — the same requests go to both, and the responses are compared to catch discrepancies before the switchover. Once confident, update the routing layer to direct traffic for this feature to the new service instead of the legacy system.
Step 5: Decommission the legacy module.
Once the new service is running in production and handling the traffic without issues, remove the corresponding module from the legacy system. The legacy system is now smaller. Repeat.
Over time, the new services collectively replace the entire legacy system. The routing layer eventually becomes your primary API gateway, the legacy system is fully decommissioned, and you've done it with zero big-bang risk.
A Practical Modernisation Roadmap
The Strangler Fig pattern is the methodology. The roadmap is the sequence of decisions that make it work.
Phase 1: Assessment (Weeks 1–3)
Before writing a line of code, understand what you have. Document every component of the legacy system, every integration point, and every external dependency. Interview the people who know it best — the engineers who've worked on it longest, the support team who know what breaks most often, the business stakeholders who know which capabilities are most critical.
Produce:
- A component inventory with dependency mappings
- A list of the ten most painful maintenance areas (high cost, high risk, or high change frequency)
- A data model audit — what databases exist, what do they contain, how does data flow between them
- An integration map — what external systems, APIs, or partners does the legacy system talk to
This phase surfaces the scope. Most teams find it larger than they assumed.
Phase 2: Foundation (Weeks 4–8)
Before extracting any modules, build the infrastructure that the new system needs:
- Routing layer: The façade or API gateway that gives you traffic control. Nothing else is possible without this.
- CI/CD pipeline: The new modules will be deployed independently. Automated testing and deployment pipelines must exist before the first module goes to production.
- Observability: Monitoring, logging, and alerting for both the legacy system and the new services during the transition. You need to know immediately if a switchover creates problems.
- Test coverage for the legacy system: Before extracting modules, you need tests that verify the legacy system's current behaviour, so you can confirm that the replacement behaves identically.
Phase 3: Incremental Extraction (Months 2–N)
Execute the Strangler Fig pattern module by module, prioritised by the pain/value analysis from Phase 1. A typical extraction cycle takes 4–8 weeks per module. The sequence matters: extract modules with the fewest dependencies first, then tackle more interconnected ones as the team builds familiarity with the process.
For each module:
- Specify the required behaviour from the legacy system's actual behaviour (not assumed documentation)
- Build and test the replacement
- Run a parallel period with comparison testing
- Switch traffic and monitor
- Decommission and move to the next
Phase 4: Data Migration
Data is almost always the most complex part of a legacy modernisation. The legacy system may have a single monolithic database that all modules share. As modules are extracted to independent services, their data needs to migrate to independent data stores.
For complex migrations where the database schema is tightly coupled to legacy application logic, Change Data Capture (CDC) tools like Debezium can replicate data from the legacy database to new databases in near-real-time during the transition, keeping both in sync without a big-bang data cutover.
Schema changes should be backwards-compatible during the migration period — the old schema should remain functional while the new schema is being adopted, with a clean cutover once all consumers have migrated.
Phase 5: Decommission
The end state: the legacy system is fully replaced, the routing layer serves as your primary API gateway, and the old codebase is archived. This phase involves confirming that no traffic reaches the legacy system, removing legacy dependencies from your infrastructure, and formally shutting down the old servers and databases.
What Makes Modernisations Fail
Understanding the failure modes is as important as understanding the methodology:
Scope creep during extraction. Each module extraction should replicate existing behaviour, not improve it. Adding new features during a modernisation expands scope, extends timeline, and makes it harder to verify correctness (you can't compare outputs if one system does things the other doesn't). Build new features after the module is successfully extracted and stable.
Neglecting the data model. Modernisations that only address the application layer without a data strategy create new services that are still coupled to legacy data structures. Address the data model explicitly as part of each module extraction.
Moving too fast. The appeal of parallel running is that it feels slow. Teams want to switch to the new service and move on. But the parallel period is where you catch the edge cases — the obscure transaction that processes differently, the error handling path that the old system handles in a way you didn't replicate. Give each switchover enough observation time.
Skipping the assessment phase. Teams that jump straight to building often discover mid-build that a dependency they didn't map prevents them from extracting the module cleanly. The assessment phase isn't bureaucracy — it's the information that makes everything else faster.
FAQ
What is the Strangler Fig pattern in software development? It's an incremental modernisation strategy where you gradually replace parts of a legacy system with new services, without shutting down the old system first. A routing layer directs traffic to new services as they become ready, while the legacy system continues to handle everything else. The old system "dies" gradually as new services replace its modules, rather than being killed all at once in a high-risk big-bang cutover.
How long does legacy software modernisation take? It depends heavily on the size and complexity of the legacy system, but most meaningful modernisations are 6–18 month efforts. Trying to compress this timeline significantly increases risk. The assessment and foundation phases typically take 6–8 weeks. Each module extraction cycle is 4–8 weeks. A system with 8–10 significant modules would be a 12–18 month programme at a realistic pace. [VERIFY: timeline estimate based on typical project scope]
Can we continue adding new features during a modernisation? Yes, but it requires discipline. New features should be built in the new system (the emerging architecture), not in the legacy system. This prevents you from deepening the investment in code you're planning to decommission. It does require the new system's infrastructure to be ready early enough to host new features — which is one of the arguments for doing the foundation phase properly before starting feature development.
Is it ever the right choice to do a full rewrite? Sometimes, but rarely as the first choice. A full rewrite is appropriate when the architecture genuinely cannot support what the business needs and incremental extraction isn't possible because every part of the system is tightly coupled to every other part. Even in that case, the Strangler Fig approach — where the "new system" is built incrementally behind a routing layer — is preferable to a parallel build with a big-bang cutover. The key difference is whether incremental extraction is technically feasible.
How do we handle a legacy system with no documentation and no tests? Start by writing characterisation tests — tests that don't verify what the system should do, but what it currently does. Run the legacy system, capture its outputs for a representative set of inputs, and encode those as tests. This creates a safety net that lets you verify that extraction is correct before cutting over. It's imperfect — you can't test inputs you've never seen — but it's the fastest way to get partial coverage on an undocumented system.
Legacy software problems don't resolve themselves. Each quarter they stay unaddressed, the cost of fixing them grows and the business moves further from where it needs to be. If you're sitting on a system that's slowing your team down and limiting what's possible, reach out to our engineering team to plan a modernisation roadmap — starting with what the system actually is, not just what you think it is.
Custom Software & SaaS development · Microservices vs. monolith guide · Managing technical debt while scaling
Author: Abdul Rahaman
Last updated: August 2026