Modernizing a legacy monolith
Replacing a legacy system that has grown over time without putting operations at risk — step by step instead of a big bang.
What is this? · Playbook
A repeatable approach to a recurring challenge — situation, steps, decision points and validation. How we do it, not why. Go to overview
When this playbook applies.
A system that has grown over many years carries the business but has become hard to change: unclear boundaries, thin test coverage, knowledge concentrated in a few heads. A complete rebuild is tempting — and risky.
Objectives
- The legacy system remains operational at all times.
- Changeability and maintainability return step by step.
- Knowledge is preserved rather than lost to a rebuild.
Typical risks
- Big-bang rewrite: months without added value and a high cutover risk.
- Data migration without a proven way back.
- New and old logic drift apart — two versions of the truth.
- Unclear legacy boundaries are carried over one-to-one into the new system.
Before we build.
- Take stock: what does the system actually do, and where are the risks?
- Put characterization tests around the critical paths before changing anything.
- Identify domain boundaries (bounded contexts) independently of the legacy code.
- Define a reversible migration strategy and prove backup and restore.
How we proceed.
Strangler fig instead of a rewrite
New functionality is built alongside the legacy system; requests are rerouted function by function. The old system keeps running until the new one has safely replaced it.
Cut the boundaries first
We replace along stable domain boundaries, not along technical layers. The first boundary is the lowest-risk one with a clear benefit.
A single source of truth
During the transition, one system holds the truth for a given data area — never both. Synchronization is explicit and one-directional.
Small, reversible steps
Each rerouting can be rolled out and rolled back individually. Progress is visible every week and measurable in production.
Questions that need an answer.
Is the next boundary to be replaced stable from a business perspective — or is it still changing?
Is there a characterization test for the affected path?
Can the rerouting be reversed if it fails?
Does the source of truth remain unambiguous?
Validation
- The replaced path demonstrably behaves as before (characterization tests pass).
- Cutover and rollback have been rehearsed in staging.
- Metrics show no regression in production.
Common mistakes
- Starting the rewrite as a project before the boundaries are understood.
- Adopting unclear legacy boundaries unchanged.
- Migrating data without a proven way back.
- Taking steps too large to roll back individually.
When we deliberately take a different approach.
- If the legacy system is small, well understood and low-risk, a targeted rebuild can be cheaper than a step-by-step replacement.
- If the system is going to be shut down anyway, modernization isn't worth it — only a clean exit is.
Continue your engineering journey.
Related concepts, decisions, playbooks and perspectives — as one connected path, not a list of links.
Facing a similar challenge?
Playbooks show how we think. For your specific project, talk to our management — technical, no sales pitch.
