Legacy System Modernization Engine

Complete methodology for assessing, planning, and executing legacy system modernization — from monolith decomposition to cloud migration. Works for any tech stack, any scale.

---

Phase 1: System Assessment

Modernization Brief

system_name: "[Name]"
age_years: 0
primary_language: ""
framework: ""
database: ""
deployment: "on-prem | VM | container | serverless"
lines_of_code: 0
team_size: 0
monthly_users: 0
annual_revenue_supported: "$0"
compliance_requirements: []
known_pain_points: []
business_driver: "cost | speed | talent | risk | compliance | scale"
timeline_pressure: "low | medium | high | critical"
budget_range: "$0-$0"
sponsor: ""

Technical Debt Inventory

Score each dimension 1-5 (1=critical, 5=healthy):

Dimension	Score	Evidence
Code quality — test coverage, complexity, duplication
Architecture — coupling, modularity, clear boundaries
Infrastructure — deployment automation, monitoring, scaling
Dependencies — outdated libraries, EOL frameworks, security vulns
Data — schema quality, migration history, backup/recovery
Documentation — accuracy, coverage, onboarding effectiveness
Operations — deployment frequency, MTTR, incident rate
Security — auth patterns, encryption, audit trail, compliance gaps
Developer experience — build time, local setup, debugging tools
Business logic clarity — documented rules, test coverage of logic

Total: /50

• 40-50: Healthy — incremental improvement
• 30-39: Aging — targeted modernization
• 20-29: Legacy — systematic modernization needed
• 10-19: Critical — modernize or replace

Dependency Risk Matrix

For each major dependency:

dependency: ""
current_version: ""
latest_version: ""
eol_date: ""  # End of life
security_vulns: 0  # Known CVEs
upgrade_difficulty: "trivial | moderate | hard | rewrite"
business_risk: "low | medium | high | critical"
alternatives: []

Priority rules:

• EOL within 12 months → P0
• Known unpatched CVEs → P0
• 3+ major versions behind → P1
• No active maintainer → P1
• Everything else → P2

---

Phase 2: Strategy Selection

Modernization Strategy Decision Matrix

Strategy	When to Use	Risk	Cost	Speed	Disruption
Rehost (lift & shift)	Datacenter exit, minimal change	Low	Low	Fast	Low
Replatform (lift & optimize)	Cloud benefits without rewrite	Low-Med	Medium	Medium	Low-Med
Refactor (restructure)	Good code, bad architecture	Medium	Medium	Medium	Medium
Re-architect (rebuild patterns)	Monolith→services, new patterns	High	High	Slow	High
Rebuild (rewrite)	Small system, clear requirements	Very High	Very High	Very Slow	Very High
Replace (buy/SaaS)	Commodity functionality	Medium	Variable	Fast	High
Retire	No longer needed	None	Negative	Instant	Low
Retain (do nothing)	Working fine, other priorities	None	Ongoing	N/A	None

Strategy Selection Decision Tree

Is the system still needed?
├─ No → RETIRE
├─ Yes → Is it a commodity (CRM, email, etc.)?
│  ├─ Yes → REPLACE (buy SaaS)
│  └─ No → Is the code maintainable?
│     ├─ Yes → Is the architecture the problem?
│     │  ├─ Yes → RE-ARCHITECT (strangler fig)
│     │  └─ No → Is the infrastructure the problem?
│     │     ├─ Yes → REPLATFORM
│     │     └─ No → REFACTOR incrementally
│     └─ No → Is the system small (<50K LOC)?
│        ├─ Yes → Can requirements be clearly defined?
│        │  ├─ Yes → REBUILD
│        │  └─ No → REFACTOR + RE-ARCHITECT
│        └─ No → STRANGLER FIG (never big-bang rewrite)

The Big Rewrite Anti-Pattern

NEVER do a full rewrite of a large system. It fails 70%+ of the time because:

1. The old system keeps getting features — moving target
2. Hidden business rules only exist in code — they get lost
3. Timeline always 2-3x longer than estimated
4. Two systems to maintain during transition
5. Team burns out before completion

Always use Strangler Fig instead. Replace piece by piece.

---

Phase 3: Strangler Fig Pattern

How It Works

1. Identify a boundary — a feature, page, or API endpoint
2. Build the replacement — new stack, new patterns
3. Route traffic — proxy/facade sends requests to new or old
4. Verify parity — same behavior, same data
5. Cut over — remove the proxy, retire the old code
6. Repeat — next boundary

Strangler Facade YAML

facade_name: "[API Gateway / Reverse Proxy / BFF]"
routing_rules:
  - path: "/api/users/*"
    target: "new-service"
    status: "migrated"
    migrated_date: "2025-01-15"
  - path: "/api/orders/*"
    target: "legacy"
    status: "planned"
    target_date: "2025-Q2"
  - path: "/api/reports/*"
    target: "legacy"
    status: "not-planned"
    notes: "Low priority, rarely used"

Migration Sequence Rules

1. Start with the easiest, most isolated module — build confidence
2. Then the highest-value business capability — prove ROI early
3. Leave the hardest, most coupled parts for last — team learns patterns first
4. Never migrate auth/identity early — it touches everything
5. Migrate data access layer before business logic — clean data = clean migration
6. Always keep the old system as fallback until new is proven

Dual-Write / Data Sync Patterns

Pattern	When	Complexity	Risk
Dual write	Both systems write simultaneously	High	Data inconsistency
CDC (Change Data Capture)	Stream changes from old→new DB	Medium	Lag, ordering
ETL batch sync	Periodic bulk sync	Low	Stale data
Event sourcing bridge	Events from old, replay in new	High	Schema mapping
Read from new, write to old	Transition period	Medium	Routing complexity

Golden rule: Pick ONE source of truth. Never let both systems own the same data simultaneously.

---

Phase 4: Monolith Decomposition

Domain Discovery

Before splitting a monolith, identify bounded contexts:

1. Event Storming (preferred) — sticky notes for domain events, commands, aggregates
2. Code analysis — find clusters of related classes/tables
3. Team analysis — which teams own which features?
4. Data coupling analysis — which tables are joined together?

Bounded Context YAML

context_name: ""
description: ""
team: ""
entities: []
commands: []
events_published: []
events_consumed: []
database_tables: []
external_integrations: []
coupling_score: 0  # 0=independent, 10=deeply coupled
extraction_difficulty: "easy | moderate | hard | very-hard"
business_value: "low | medium | high | critical"

Extraction Priority Matrix

Plot contexts on: Business Value (Y) × Extraction Difficulty (X)

	Easy	Moderate	Hard
High value	🟢 Do first	🟡 Do second	🟠 Plan carefully
Medium value	🟢 Quick win	🟡 Evaluate ROI	🔴 Probably not worth it
Low value	🟡 If easy, why not	🔴 Skip	🔴 Definitely skip

Service Extraction Checklist

For each service being extracted:

• Bounded context clearly defined
• API contract designed (OpenAPI spec)
• Database separated (no shared tables)
• Authentication/authorization integrated
• Event publishing for cross-service communication
• Circuit breaker for calls back to monolith
• Monitoring and alerting configured
• Deployment pipeline independent
• Feature flag for traffic routing
• Rollback plan documented
• Performance baseline captured (before/after)
• Data migration script tested
• Integration tests with monolith passing
• Runbook for on-call written

---

Phase 5: Database Modernization

Database Migration Strategies

Strategy	Description	Downtime	Risk
Parallel run	New DB alongside old, sync both	Zero	High complexity
Blue-green	Full copy, switch DNS	Minutes	Medium
Rolling	Migrate table by table	Zero per table	Medium
Big bang	Stop, migrate, start	Hours	High

Schema Evolution Rules

1. Always additive — add columns/tables, never remove in the same release
2. Two-phase removal — Release 1: stop writing. Release 2: drop column (after backfill verified)
3. Default values always — every new column gets a default
4. Backward compatible — old code must work with new schema during rollout
5. Index concurrently — never lock production tables
6. Test with production-scale data — 100 rows ≠ 100M rows

Data Quality Gates

Before migrating data:

table: ""
row_count_source: 0
row_count_target: 0
count_match: false
checksum_match: false
null_analysis: "pass | fail"
referential_integrity: "pass | fail"
business_rule_validation: "pass | fail"
sample_manual_review: "pass | fail"
performance_benchmark: "pass | fail"
rollback_tested: false

Rule: All gates must pass before cutover. No exceptions.

---

Phase 6: Cloud Migration

Cloud Readiness Assessment

Score each workload:

Factor	Score (1-5)	Notes
Stateless design
Configuration externalized
Logging to stdout
Health check endpoint
Graceful shutdown
Horizontal scalability
Secret management
12-factor compliance

35-40: Cloud-native ready 25-34: Minor modifications needed 15-24: Significant refactoring 8-14: Major redesign required

Cloud Migration Checklist

• Network architecture designed (VPC, subnets, security groups)
• Identity and access management configured
• Data residency requirements verified
• Compliance mapping (cloud controls ↔ requirements)
• Cost estimation completed (TCO comparison)
• Disaster recovery plan updated
• Monitoring and alerting migrated
• DNS and certificate management planned
• CDN configuration
• Load testing in cloud environment
• Security scanning pipeline
• Backup and restore verified
• Runbooks updated for cloud operations
• Team trained on cloud platform
• Vendor lock-in assessment

Cost Optimization from Day 1

• Right-size instances — start small, scale up with data
• Reserved/committed use — only after 3 months of usage data
• Spot/preemptible — for batch jobs, CI/CD, dev/test
• Auto-scaling — scale down at night, weekends
• Storage tiers — hot/warm/cold/archive based on access patterns
• Tag everything — cost allocation by team, service, environment
• Monthly review — unused resources, oversized instances

---

Phase 7: API Modernization

API Wrapping Pattern

For legacy systems without APIs:

1. Screen scraping adapter — parse HTML/mainframe screens
2. Database tap — read directly from legacy DB (read-only!)
3. File-based integration — watch folders, parse files
4. Message queue bridge — legacy writes to queue, new reads
5. RPC wrapper — expose existing functions via REST/gRPC

API Contract-First Migration

endpoint: "/api/v2/orders"
legacy_source: "stored_procedure: sp_GetOrders"
new_implementation: "orders-service"
migration_status: "legacy | dual-run | new-only"
contract_changes:
  - field: "order_date"
    old_format: "MM/DD/YYYY string"
    new_format: "ISO 8601"
    adapter: "date_format_adapter"
  - field: "status"
    old_values: ["A", "C", "P"]
    new_values: ["active", "completed", "pending"]
    adapter: "status_code_mapper"
parity_tests: 47
parity_passing: 47

---

Phase 8: Testing Strategy

Migration Testing Pyramid

         /  Smoke Tests  \           ← Whole system alive?
        / Parity Tests    \          ← Same behavior old vs new?
       / Integration Tests \         ← Services work together?
      / Contract Tests      \        ← API contracts honored?
     / Performance Tests     \       ← Not slower than before?
    / Data Validation Tests   \      ← Data migrated correctly?
   /  Unit Tests               \     ← New code works?

Parity Testing Framework

For EVERY migrated feature:

feature: ""
test_type: "api_parity | ui_parity | data_parity"
method: "shadow traffic | replay | parallel run"
sample_size: 0
match_rate: "0%"  # Target: 99.9%+
mismatches_investigated: 0
mismatches_accepted: 0  # Known intentional differences
mismatches_bugs: 0
sign_off: false

Shadow traffic — copy production requests to new system, compare responses (don't serve new responses to users yet).

Performance Regression Rules

• P95 latency must not increase >10% vs legacy
• Throughput must meet or exceed legacy under same load
• Database query count must not increase per request
• Memory usage must not increase >20%
• If ANY metric regresses → investigate before proceeding

---

Phase 9: Team & Process

Modernization Team Structure

Role	Responsibility	When Needed
Modernization Lead	Strategy, sequencing, blockers	Full-time
Legacy Expert	Knows where the bodies are buried	Part-time, on-call
New Platform Engineer	Builds target architecture	Full-time
Data Engineer	Migration, sync, validation	Phase-dependent
QA/Test Engineer	Parity testing, automation	Full-time
DevOps/Platform	CI/CD, infrastructure	Part-time
Product Owner	Business priority, acceptance	Part-time

Knowledge Mining from Legacy

The most dangerous part of modernization is losing undocumented business rules.

1. Code archaeology — git blame, find oldest unchanged code, understand why
2. Interview stakeholders — "What would break if we changed X?"
3. Production log analysis — what edge cases actually occur?
4. Error handling review — each catch block is a documented business rule
5. Test suite review — tests describe expected behavior
6. Configuration review — magic numbers, feature flags, overrides

Communication Plan

Audience	Frequency	Content
Executive sponsor	Bi-weekly	Progress, risks, budget, timeline
Engineering team	Weekly	Sprint goals, technical decisions, blockers
Dependent teams	Monthly	Upcoming changes, migration dates, API changes
End users	Per migration	What's changing, when, how it affects them

---

Phase 10: Risk Management

Top 10 Modernization Risks (Pre-Built)

#	Risk	Likelihood	Impact	Mitigation
1	Undocumented business rules lost	High	Critical	Code archaeology + stakeholder interviews + parity tests
2	Timeline underestimation	Very High	High	2x initial estimate, phase-gated checkpoints
3	Data migration corruption	Medium	Critical	Checksums, parallel runs, rollback plans
4	Feature parity gaps	High	High	Shadow traffic testing, user acceptance testing
5	Team knowledge loss (people leave)	Medium	High	Document everything, pair programming, knowledge sharing
6	Legacy system changes during migration	High	Medium	Feature freeze or dual-write contract
7	Performance regression	Medium	High	Load testing at every phase, performance budgets
8	Scope creep (improve while migrating)	Very High	Medium	Strict "migrate, don't improve" rule for Phase 1
9	Integration failures	Medium	High	Contract testing, circuit breakers, fallback routing
10	Stakeholder fatigue	High	Medium	Quick wins early, visible progress dashboard

Kill Criteria

Stop the modernization if:

• Budget exceeds 2x initial estimate with <50% complete
• Key business rules can't be verified after migration
• Team attrition >30% during project
• Legacy system stability degrades due to migration work
• Business context changes (M&A, pivot, sunset)

If kill criteria triggered: Stabilize what's done, document learnings, reassess in 6 months.

---

Phase 11: Patterns & Playbooks

Language/Framework Migration Patterns

Java → Modern Java (8→17+)

• Records, sealed classes, pattern matching
• Virtual threads (Project Loom) for thread-per-request
• Migrate build: Maven→Gradle or update Maven plugins
• Spring Boot 2→3: javax→jakarta namespace

Python 2→3

• Use 2to3 tool for automated conversion
• Fix: print(), division, unicode, dict methods
• Upgrade dependencies (check py3 compat)

jQuery→React/Vue

• Extract components from page sections
• State management replaces DOM manipulation
• Event handlers become component methods
• Ajax calls become API service layer

Monolith→Microservices

• Strangler fig (see Phase 3)
• Start with read models (reporting, search)
• Extract stateless services first
• Shared database → database-per-service last

On-Prem→Cloud

• Rehost first (lift & shift)
• Then replatform (managed services)
• Then re-architect (cloud-native patterns)
• Never skip steps — each proves value

COBOL/Mainframe Modernization

1. API wrapping — expose CICS/IMS transactions as REST APIs
2. Screen scraping — automate 3270 terminal interactions
3. Gradual extraction — one transaction at a time
4. Data replication — DB2/VSAM → PostgreSQL/cloud DB
5. Rule extraction — COBOL paragraphs → business rule engine
6. Never rewrite all at once — decades of business logic = decades of edge cases

Microservices Anti-Patterns to Avoid

Anti-Pattern	Symptom	Fix
Distributed monolith	Services must deploy together	Identify and break coupling
Shared database	Multiple services write same tables	Database-per-service
Synchronous chains	A calls B calls C calls D	Async events, choreography
Nano-services	Hundreds of tiny services	Merge related services
Shared libraries for business logic	Library update breaks consumers	Duplicate code > shared coupling
No API versioning	Breaking changes cascade	Semantic versioning, deprecation policy

---

Phase 12: Metrics & Reporting

Modernization Health Dashboard

project: ""
assessment_date: ""
overall_health: "green | yellow | red"

progress:
  modules_total: 0
  modules_migrated: 0
  modules_in_progress: 0
  percent_complete: "0%"
  
velocity:
  modules_per_sprint: 0
  estimated_completion: ""
  on_track: true

quality:
  parity_test_pass_rate: "0%"
  production_incidents_from_migration: 0
  rollbacks: 0
  
risk:
  open_risks: 0
  p0_risks: 0
  blocked_items: 0

cost:
  budget_total: "$0"
  budget_spent: "$0"
  budget_remaining: "$0"
  burn_rate_monthly: "$0"

100-Point Modernization Quality Rubric

Dimension	Weight	Score (0-10)	Weighted
Strategy clarity	15%
Risk management	15%
Testing rigor	15%
Data integrity	15%
Architecture quality	10%
Team capability	10%
Stakeholder alignment	10%
Documentation	10%
Total	100%		/100

90-100: Exemplary — reference project 70-89: Strong — minor improvements 50-69: Adequate — address gaps Below 50: At risk — pause and reassess

Weekly Status Template

## Modernization Status — Week of [DATE]

### Progress
- Modules migrated this week: [N]
- Total migrated: [N]/[TOTAL] ([X]%)
- On track for [TARGET DATE]: [Yes/No]

### Completed
- [What shipped this week]

### In Progress
- [What's being worked on]

### Blockers
- [What's stuck and what's needed]

### Risks
- [New or changed risks]

### Next Week
- [Plan for next sprint]

---

Edge Cases

"We need to modernize but can't stop adding features"

• Strangler fig — modernize around new features
• Feature freeze on legacy module ONLY when that module is being migrated
• New features build in new stack from day 1

"We don't know what the system does"

• Start with observability: instrument logging, tracing, metrics
• Run for 2-4 weeks to understand actual usage patterns
• Code coverage analysis shows what code is actually executed
• Interview longest-tenured team members

"Multiple systems need modernizing simultaneously"

• Sequence by dependency order — downstream first
• Shared services (auth, data) get modernized once, reused
• Never parallelize more than 2 modernization streams

"The original developers are gone"

• Treat code as the documentation
• Invest 2-4 weeks in code archaeology before any migration work
• Pair new developers with business stakeholders
• Write tests for existing behavior before changing anything

"We're being acquired / merging systems"

• Map overlapping functionality first
• Pick "winner" system per domain — don't merge codebases
• API integration layer between systems
• 18-month realistic timeline for full consolidation

"Compliance requires the old system"

• Maintain compliance evidence chain during migration
• Dual-audit period with both systems
• Get compliance team involved in migration planning from Day 1
• Document control mapping: old control → new implementation

---

Natural Language Commands

Command	Action
"Assess this system for modernization"	Run full Technical Debt Inventory
"Which modernization strategy should we use?"	Walk through Strategy Decision Tree
"Plan a strangler fig migration"	Generate Strangler Facade YAML + sequence
"Decompose this monolith"	Domain discovery + Bounded Context mapping
"Migrate this database"	Data Quality Gates + migration strategy
"Check cloud readiness"	Run Cloud Readiness Assessment
"Create a migration testing plan"	Build Testing Pyramid with parity tests
"What are the risks?"	Generate Top 10 risk register
"How do we migrate from [X] to [Y]?"	Pattern-specific playbook
"Status update for modernization"	Generate Weekly Status Template
"Score this modernization project"	Run 100-Point Quality Rubric
"Should we kill this modernization?"	Evaluate Kill Criteria