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

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 |