legacy modernization

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.

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): DimensionScoreEvidenceCode quality — test coverage, complexity, duplicationArchitecture — coupling, modularity, clear boundariesInfrastructure — deployment automation, monitoring, scalingDependencies — outdated libraries, EOL frameworks, security vulnsData — schema quality, migration history, backup/recoveryDocumentation — accuracy, coverage, onboarding effectivenessOperations — deployment frequency, MTTR, incident rateSecurity — auth patterns, encryption, audit trail, compliance gapsDeveloper experience — build time, local setup, debugging toolsBusiness 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

Modernization Strategy Decision Matrix

StrategyWhen to UseRiskCostSpeedDisruptionRehost (lift & shift)Datacenter exit, minimal changeLowLowFastLowReplatform (lift & optimize)Cloud benefits without rewriteLow-MedMediumMediumLow-MedRefactor (restructure)Good code, bad architectureMediumMediumMediumMediumRe-architect (rebuild patterns)Monolith→services, new patternsHighHighSlowHighRebuild (rewrite)Small system, clear requirementsVery HighVery HighVery SlowVery HighReplace (buy/SaaS)Commodity functionalityMediumVariableFastHighRetireNo longer neededNoneNegativeInstantLowRetain (do nothing)Working fine, other prioritiesNoneOngoingN/ANone

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: The old system keeps getting features — moving target Hidden business rules only exist in code — they get lost Timeline always 2-3x longer than estimated Two systems to maintain during transition Team burns out before completion Always use Strangler Fig instead. Replace piece by piece.

How It Works

Identify a boundary — a feature, page, or API endpoint Build the replacement — new stack, new patterns Route traffic — proxy/facade sends requests to new or old Verify parity — same behavior, same data Cut over — remove the proxy, retire the old code 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

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

Dual-Write / Data Sync Patterns

PatternWhenComplexityRiskDual writeBoth systems write simultaneouslyHighData inconsistencyCDC (Change Data Capture)Stream changes from old→new DBMediumLag, orderingETL batch syncPeriodic bulk syncLowStale dataEvent sourcing bridgeEvents from old, replay in newHighSchema mappingRead from new, write to oldTransition periodMediumRouting complexity Golden rule: Pick ONE source of truth. Never let both systems own the same data simultaneously.

Domain Discovery

Before splitting a monolith, identify bounded contexts: Event Storming (preferred) — sticky notes for domain events, commands, aggregates Code analysis — find clusters of related classes/tables Team analysis — which teams own which features? 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) EasyModerateHardHigh value🟢 Do first🟡 Do second🟠 Plan carefullyMedium value🟢 Quick win🟡 Evaluate ROI🔴 Probably not worth itLow 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

Database Migration Strategies

StrategyDescriptionDowntimeRiskParallel runNew DB alongside old, sync bothZeroHigh complexityBlue-greenFull copy, switch DNSMinutesMediumRollingMigrate table by tableZero per tableMediumBig bangStop, migrate, startHoursHigh

Schema Evolution Rules

Always additive — add columns/tables, never remove in the same release Two-phase removal — Release 1: stop writing. Release 2: drop column (after backfill verified) Default values always — every new column gets a default Backward compatible — old code must work with new schema during rollout Index concurrently — never lock production tables 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.

Cloud Readiness Assessment

Score each workload: FactorScore (1-5)NotesStateless designConfiguration externalizedLogging to stdoutHealth check endpointGraceful shutdownHorizontal scalabilitySecret management12-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

API Wrapping Pattern

For legacy systems without APIs: Screen scraping adapter — parse HTML/mainframe screens Database tap — read directly from legacy DB (read-only!) File-based integration — watch folders, parse files Message queue bridge — legacy writes to queue, new reads 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

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

Modernization Team Structure

RoleResponsibilityWhen NeededModernization LeadStrategy, sequencing, blockersFull-timeLegacy ExpertKnows where the bodies are buriedPart-time, on-callNew Platform EngineerBuilds target architectureFull-timeData EngineerMigration, sync, validationPhase-dependentQA/Test EngineerParity testing, automationFull-timeDevOps/PlatformCI/CD, infrastructurePart-timeProduct OwnerBusiness priority, acceptancePart-time

Knowledge Mining from Legacy

The most dangerous part of modernization is losing undocumented business rules. Code archaeology — git blame, find oldest unchanged code, understand why Interview stakeholders — "What would break if we changed X?" Production log analysis — what edge cases actually occur? Error handling review — each catch block is a documented business rule Test suite review — tests describe expected behavior Configuration review — magic numbers, feature flags, overrides

Communication Plan

AudienceFrequencyContentExecutive sponsorBi-weeklyProgress, risks, budget, timelineEngineering teamWeeklySprint goals, technical decisions, blockersDependent teamsMonthlyUpcoming changes, migration dates, API changesEnd usersPer migrationWhat's changing, when, how it affects them

Top 10 Modernization Risks (Pre-Built)

#RiskLikelihoodImpactMitigation1Undocumented business rules lostHighCriticalCode archaeology + stakeholder interviews + parity tests2Timeline underestimationVery HighHigh2x initial estimate, phase-gated checkpoints3Data migration corruptionMediumCriticalChecksums, parallel runs, rollback plans4Feature parity gapsHighHighShadow traffic testing, user acceptance testing5Team knowledge loss (people leave)MediumHighDocument everything, pair programming, knowledge sharing6Legacy system changes during migrationHighMediumFeature freeze or dual-write contract7Performance regressionMediumHighLoad testing at every phase, performance budgets8Scope creep (improve while migrating)Very HighMediumStrict "migrate, don't improve" rule for Phase 19Integration failuresMediumHighContract testing, circuit breakers, fallback routing10Stakeholder fatigueHighMediumQuick 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.

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

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

Microservices Anti-Patterns to Avoid

Anti-PatternSymptomFixDistributed monolithServices must deploy togetherIdentify and break couplingShared databaseMultiple services write same tablesDatabase-per-serviceSynchronous chainsA calls B calls C calls DAsync events, choreographyNano-servicesHundreds of tiny servicesMerge related servicesShared libraries for business logicLibrary update breaks consumersDuplicate code > shared couplingNo API versioningBreaking changes cascadeSemantic versioning, deprecation policy

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

DimensionWeightScore (0-10)WeightedStrategy clarity15%Risk management15%Testing rigor15%Data integrity15%Architecture quality10%Team capability10%Stakeholder alignment10%Documentation10%Total100%/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]

"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

CommandAction"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