legacy modernization

Comprehensive legacy system modernization from assessment and strategy to monolith decomposition and cloud migration for any tech stack and scale.

1kalin@1kalin

Install

openclaw skills install @1kalin/afrexai-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.

Phase 1: System Assessment

Modernization Brief

yaml

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:

yaml

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

text

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.

Phase 3: Strangler Fig Pattern

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

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

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:

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

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:

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

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:

yaml

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

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:

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

yaml

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

text

         /  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:

yaml

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.

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

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

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

yaml

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

markdown

## 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