---
name: afrexai-legacy-modernization
description: "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

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

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

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

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

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

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

```
         /  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**.

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

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

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