My first big rewrite cost $400K and failed. The next three modernizations succeeded using a 6-phase strangler fig roadmap. Here's the complete playbook with real budget numbers.
I've led 4 legacy code modernization projects. The first one failed spectacularly: 8 months of work, $400K invested, and we rolled back to the legacy system because the replacement couldn't handle edge cases that had been accumulating in the original for 7 years. The next three succeeded. The difference was abandoning the "big rewrite" fantasy and adopting a systematic, incremental approach.
This is the complete roadmap I use now. It's not theoretical. Every step comes from real projects with real outcomes. I'll include the timelines, the costs, the mistakes, and the specific decisions that made the difference.
Before the roadmap, let me explain why the approach most people try first doesn't work. The big rewrite (build the new system from scratch, then switch over) fails for three predictable reasons:
1. The Iceberg Problem. You can see the legacy system's interface. You can't see the thousands of edge cases, business rules, and workarounds embedded in the code. The original team built most of those from production incidents that nobody documented. Your rewrite will miss them until production traffic exposes them.
At my failed rewrite, we discovered 340+ business rules in the legacy code that weren't documented anywhere. We'd accounted for about 80 of them in the new system. The first week of production traffic triggered 47 of the ones we'd missed.
2. The Moving Target Problem. While you're building the replacement, the business keeps running on the legacy system. New features get added to the legacy system because you can't pause the business for 8 months. Now you're chasing a moving target, and every new legacy feature widens the gap.
3. The All-or-Nothing Risk. A big rewrite ships as one massive change. If it works, great. If it doesn't, you roll back everything. There's no partial credit. This maximizes risk at the exact moment you can least afford it, right when you've spent months of investment.
This roadmap works in 6 phases over 12-24 months, depending on the system's size and complexity. The technical debt guide helps frame the problems and priorities before committing to the programme. Each phase delivers measurable value on its own, so you're never more than one phase away from a viable stopping point.
Figure 1. The six phases separate discovery and protection from extraction, data work and retirement.
Don't touch the code. Don't plan the architecture. Just understand what you have.
Step 1: Map the Runtime Behavior
RUNTIME MAPPING CHECKLIST:
[ ] Instrument all entry points (APIs, cron jobs, message consumers)
[ ] Log every external dependency call (databases, APIs, file systems)
[ ] Capture actual traffic patterns (which endpoints get hit, how often)
[ ] Identify peak load patterns
[ ] Map data flows end-to-end for top 10 use cases
[ ] Document all integration points with other systems
TOOLS:
- Application Performance Monitoring (Datadog, New Relic, or OpenTelemetry)
- Request tracing (add correlation IDs if they don't exist)
- Query planning/execution statistics (pg_stat_statements for PostgreSQL)
At one modernization project, this step revealed that 3 of our top 5 API endpoints weren't in any documentation. They'd been added by a contractor 4 years earlier, never documented, and were processing $2.3M in monthly transactions. If we'd rebuilt without this discovery, those transactions would have failed silently.
OpenTelemetry supplies instrumentation for traces, metrics and logs. PostgreSQL’s pg_stat_statements aggregates query planning and execution statistics. Use these alongside the runtime map.[1][2]
Step 2: Create the Business Rule Inventory
This is the most tedious and most important step. Go through the legacy code function by function and catalog every business rule, validation, transformation, and edge case handling.
typescript
// Example business rule inventory entryinterface BusinessRule { id: string; description: string; location: string; // file and line number inputs: string[]; outputs: string[]; edgeCases: string[]; hasTests: boolean; lastModified: string; modifiedBy: string; businessOwner: string; criticality: "critical" | "high" | "medium" | "low";}const exampleRule: BusinessRule = { id: "BR-047", description: "Orders over $10,000 require manual approval unless customer has tier-3 status AND account age > 2 years AND no chargebacks in 12 months", location: "src/orders/validation.py:234-289", inputs: ["order.total", "customer.tier", "customer.created_at", "customer.chargeback_history"], outputs: ["approval_required: boolean", "auto_approve_reason: string | null"], edgeCases: [ "Currency conversion happens BEFORE threshold check", "Tier-3 downgrade during order processing causes race condition (see INCIDENT-2023-041)", "Chargeback window uses business days, not calendar days" ], hasTests: false, lastModified: "2024-03-15", modifiedBy: "former_contractor", businessOwner: "payments_team", criticality: "critical",};
Yes, this is slow. Budget 2-3 weeks for a medium-sized system. It saves you months of debugging later.
Step 3: Assess the Architecture
Map the current system's architecture including all the ugly parts. Don't pretend the shared database doesn't exist. Don't gloss over the 15 cron jobs that coordinate through file drops.
ARCHITECTURE ASSESSMENT TEMPLATE:
Components: [list every service, database, queue, cron job]
Data Stores:
Primary DB: [type, version, schema size, data volume]
Secondary stores: [caches, search indexes, file storage]
Shared state: [anything accessed by multiple components]
Integration Points:
Internal: [service-to-service communication methods]
External: [third-party APIs, partner integrations]
Data feeds: [imports, exports, ETL processes]
Known Pain Points:
Performance: [what's slow and why]
Reliability: [what breaks and how often]
Scalability: [what won't handle 2x growth]
Hidden Dependencies:
[Things that will break in surprising ways when you change stuff]
Before changing any code, build a safety net. This phase is about reducing the risk of all future changes.
Step 1: Add Observability
If the legacy system doesn't have proper monitoring, add it before you change anything. You need to know what "normal" looks like so you can detect when your changes break something.
OBSERVABILITY CHECKLIST:
[ ] Health check endpoints for every component
[ ] Latency tracking (p50, p95, p99) for all API endpoints
[ ] Error rate tracking by endpoint and error type
[ ] Database query performance monitoring
[ ] Queue depth and processing lag monitoring
[ ] Business metric dashboards (orders/min, payments/min, etc.)
[ ] Alerting thresholds set based on 30 days of baseline data
Step 2: Write Characterization Tests
Characterization tests capture current behavior before a change. Michael Feathers describes building tests to sense how existing code works, then checking changes against those observations. The goal is to capture what the system actually does, including bugs that users have adapted to.[3]
typescript
// Characterization test exampledescribe("Order total calculation (characterization)", () => { // This test documents CURRENT behavior, not CORRECT behavior // Note: the 2% discount is undocumented but removing it broke // integration with partner-billing-system in 2023 it("applies undocumented 2% discount for partner orders", () => { const order = createOrder({ source: "partner-api", items: [{ sku: "WIDGET-1", price: 100.00, qty: 1 }], }); const total = calculateOrderTotal(order); // Expected: 100.00, Actual: 98.00 // This "bug" is a feature that partner-billing-system depends on expect(total).toBe(98.00); }); it("rounds currency to 2 decimal places using banker's rounding", () => { const order = createOrder({ items: [{ sku: "WIDGET-2", price: 10.005, qty: 1 }], }); const total = calculateOrderTotal(order); // Banker's rounding: .005 rounds to .00 (not .01) expect(total).toBe(10.00); });});
Write characterization tests for every critical path identified in Phase 1. Target: 80%+ code coverage on business logic. Use those tests to detect changes in the critical behavior they cover.
Now you start replacing legacy code, using the strangler fig pattern. The key principle: every change is small, reversible, and independently deployable.[4]
Step 1: Identify Extraction Boundaries
Look for natural seams in the legacy system where you can insert a routing layer. Use dependency mapping to examine the state and consumers that cross a proposed boundary.
EXTRACTION BOUNDARY CRITERIA:
Good boundaries:
- Clear input/output contract
- Limited shared state with other components
- High business value or high pain (worth the investment)
- Strong characterization test coverage
- Low coupling to other legacy components
Bad boundaries:
- Deeply intertwined with other components
- Shared database tables with unclear ownership
- Complex transaction boundaries
- Poorly understood business rules
Step 2: Build the Routing Layer
Insert a proxy, API gateway, or feature flag system between clients and the legacy system. This lets you route traffic between old and new implementations. Route each write to one authoritative implementation. Compare alternative output through a side-effect-free evaluation or isolated replay.
Figure 2. The routing decision selects one implementation for the production write.
TRAFFIC MIGRATION SCHEDULE:
Week 1: 1% of traffic to new implementation (canary)
Week 2: 5% of traffic (if Week 1 metrics are healthy)
Week 3: 10% of traffic
Week 4: 25% of traffic
Week 5: 50% of traffic
Week 6: 75% of traffic
Week 7: 90% of traffic
Week 8: 100% of traffic
ROLLBACK TRIGGER (revert to previous percentage immediately):
- Error rate increases >0.5% over baseline
- Latency p99 increases >20% over baseline
- Any data consistency issue detected
- Any business metric anomaly (conversion rate, order value, etc.)
As you extract components, decouple the data layer. This is the hardest part of any modernization project.
Choose a data strategy with an explicit partial-failure and recovery design. AWS’s transactional outbox guidance explains how independent writes can leave systems inconsistent.[5]
The Data Migration Strategy:
OPTION A: Shared Database (Temporary)
New service reads/writes to legacy database
Pro: Simple, fast to implement
Con: Couples new service to legacy schema
When: Early in migration, for non-critical data
OPTION B: Change Data Capture (CDC)
Sync data from legacy DB to new service's DB
Pro: New service has its own schema
Con: Eventual consistency, CDC pipeline complexity
When: Mid-migration, for read-heavy data
OPTION C: Dual Write
Application writes to both old and new databases
Pro: Both systems receive writes when both operations succeed
Con: Partial failure can leave the systems inconsistent
When: Only with a defined consistency and recovery strategy
OPTION D: Full Migration
Move all data to new database, update all consumers
Pro: Clean break, no ongoing sync
Con: Big bang risk for the data layer
When: Final step, after all consumers are migrated
I've used all four options in different projects. Option B (CDC) with a tool like Debezium is my default recommendation. It gives you independence without the risk of dual writes.
Debezium captures database changes as events for consuming applications. A CDC migration still needs lag monitoring, replay handling and reconciliation before cutover.[6]
With components extracted and data decoupled, modernize the extracted services. Now you can safely upgrade frameworks, languages, and patterns because each service is independent.
MODERNIZATION PRIORITIES (in order):
1. Automated testing (if not already at 80%+ coverage)
2. CI/CD pipeline (automated deployment with rollback)
3. Observability (structured logging, distributed tracing, metrics)
4. Security (dependency updates, vulnerability scanning)
5. Performance (caching, query optimization, connection pooling)
6. Developer experience (local dev setup, documentation, onboarding)
7. Technology upgrades (language versions, framework versions)
Note: Items 1-3 should happen DURING extraction, not after.
Items 4-7 can wait until the service is stable.
The legacy system is still running, handling whatever hasn't been extracted yet. Don't rush to turn it off.
LEGACY RETIREMENT CHECKLIST:
[ ] All critical paths migrated to new services
[ ] All traffic routed away from legacy (0% legacy traffic for 30+ days)
[ ] All data synced and verified in new systems
[ ] All integration partners updated and tested
[ ] All cron jobs migrated or replaced
[ ] Legacy monitoring confirms zero activity for 30 days
[ ] Backup of legacy system and data created and verified
[ ] Retirement date communicated to all stakeholders
[ ] Kill switch tested (can you re-enable legacy if needed?)
ONLY AFTER ALL BOXES CHECKED: Shut down legacy system
Keep the code repository archived (never delete it)
Keep database backups for the approved legal, operational and recovery retention period
The savings come from: reduced incident costs, faster feature delivery, lower maintenance overhead, and reduced turnover (engineers don't leave when the codebase is improving).
Most modernization advice focuses on the technology: which framework to use, how to structure the new services, what database to choose. I think the technology decisions are the least important part of a modernization project.
The modernizations I've seen fail all had good technology choices. The modernizations I've seen succeed all had good business alignment. The difference is whether leadership understands what they're investing in, agrees with the timeline, and commits to protecting the team's capacity.
A modernization project with average technology choices and strong executive support will succeed. A modernization project with perfect technology choices and weak executive support will be canceled at month 6 when a revenue target gets missed and someone asks "why are 4 engineers not working on features?"
Before you choose a single technology, get a written commitment from leadership on the team size, the timeline, and the capacity protection. The refactor-or-rewrite framework provides another check on the proposed scope. That document is worth more than any architecture diagram.
LEGACY MODERNIZATION ROADMAP
Phase 1: UNDERSTAND (Weeks 1-4)
[ ] Runtime behavior mapped
[ ] Business rule inventory created
[ ] Architecture assessed and documented
[ ] Pain points prioritized
Phase 2: PROTECT (Weeks 5-8)
[ ] Observability added to legacy system
[ ] Characterization tests written (80%+ on critical paths)
[ ] Baseline metrics established
[ ] Rollback procedures documented
Phase 3: STRANGLE (Months 3-6)
[ ] Extraction boundaries identified
[ ] Routing layer built
[ ] First component extracted
[ ] Traffic migration complete for first component
Phase 4: DECOUPLE (Months 6-12)
[ ] Data migration strategy selected per component
[ ] CDC or sync pipeline running
[ ] New services on independent databases
[ ] Legacy database dependencies eliminated
Phase 5: MODERNIZE (Months 12-18)
[ ] Testing, CI/CD, observability for all new services
[ ] Security and performance optimized
[ ] Developer experience improvements shipped
[ ] Technology stack current
Phase 6: RETIRE (Months 18-24)
[ ] All traffic migrated
[ ] Legacy system idle for 30+ days
[ ] All integrations updated
[ ] Legacy system archived and shut down
TOTAL TIMELINE: 12-24 months (varies by complexity)
This roadmap isn't fast. It isn't exciting. It won't make a good conference talk. But it works. And in the world of legacy modernization, "it works" is the only metric that matters.
Frequently asked questions
Why map runtime behavior before replacing legacy code?
Runtime traces and traffic observations help reveal entry points, dependencies and workflows that documentation may omit. Combine that evidence with a business-rule inventory so that the replacement is tested against the behavior people actually depend on.
What do characterization tests establish?
They capture observed behavior before a change. That can include behavior that looks accidental but has become part of a consumer’s expectations. Review those expectations with the business and add separate tests when the intended behavior must change.
Can shadow comparison create the same order twice?
Calling both production create methods can duplicate writes and downstream effects. Route a write to one authoritative implementation. Use a side-effect-free evaluation or isolated replay when comparing alternatives, and verify how the comparison handles external dependencies.
Does change data capture remove migration risk?
CDC streams database changes to consumers, which can support a gradual move to a separate store. The migration still needs to handle lag, replay, duplicates, schema changes and reconciliation. Validate those paths before treating the new store as authoritative.
Architecture fitness functions are automated tests for your system's structural properties. Here's how to implement the 5 most impactful ones and integrate them into your CI pipeline.
No single person can hold a large codebase in their head. A knowledge graph externalizes understanding into a queryable structure. Here's the 4-week playbook to build one.
Compare monorepo vs polyrepo trade-offs for code discovery, ownership and shared contracts. Use practical search and change tasks to assess your own team.
Map dependencies in your codebase across imports, runtime calls, shared data and job order. Find hidden coupling and enforce useful architecture boundaries.
Recognise a technical debt death spiral through delivery friction, recurring incidents and lost context, then stabilise one area and measure a focused recovery.