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

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

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)

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

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:

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

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

Phase 10: Risk Management

Top 10 Modernization Risks (Pre-Built)

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

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

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