Architect Role Legacy Systems Modernization Playbook

Comparing blind AI prompt refactoring against structured 4-phase architecture recovery.

Code Archaeology & Dependency Mapping

Architect Role: Directs AI to map entry points, cross-module couplings, and unindexed database queries.

Latent Invariant & Side-Effect Extraction

Architect Role: Identifies non-negotiable business rules, implicit null-checks, and implicit accumulator mutations.

Executable Blueprint & Golden Master Synthesis

Architect Role: Structures extracted invariants into typed OpenAPI schemas, error taxonomies, and characterization test suites.

AI-Supervised Modernization & Strangler Migration

Architect Role: Executes modernization via iterative AI prompt passes, supervising each diff against the recovered blueprint.

The 4 extracted artifacts required to build an AI-executable prompt brief from legacy code.

// LegacyClaimsProcessor.java - Last updated 2014 by unknown dev
public Map processClaim(Map rawInput) {
    Connection conn = DBConnection.getGlobal();
    String claimId = (String) rawInput.get("ID");
    double amt = Double.parseDouble(rawInput.get("AMT").toString());
    
    // Hidden side-effect 1: Direct mutate global accumulator table
    Statement s = conn.createStatement();
    s.executeUpdate("UPDATE acc_tbl SET ytd = ytd + " + amt + " WHERE p_id = '" + rawInput.get("PID") + "'");
    
    // Obscure undocumented business rule (Regulatory CA Patch 2012)
    if ("CA".equals(rawInput.get("ST")) && amt > 5000.0) {
        if (rawInput.get("OVR") == null) {
            // Implicit state mutation without error code
            s.executeUpdate("INSERT INTO audit_log VALUES ('" + claimId + "', 'SUSPENDED_REVIEW')");
            rawInput.put("STATUS", "HOLD");
            return rawInput;
        }
    }
    rawInput.put("STATUS", "APPROVED");
    return rawInput;
}

• Untyped dynamic Map objects hide required and optional field structures.
• Direct inline SQL injection vulnerability and implicit database mutations bypass ORM transaction boundaries.
• Undocumented 2012 California regulatory logic silently suspends claims without standard error taxonomy.
• Swallows runtime exceptions and returns raw mutated input maps with ambiguous status strings.

• AI coding tools convert Map to a simple TypeScript interface but drop the accumulator database mutation.
• AI simplifies the "CA" state check, mistaking it for dead legacy code and causing compliance violations.
• AI fails to establish transaction isolation, resulting in corrupt year-to-date (YTD) accumulator balances.

POST /api/v2/claims/adjudicate
Content-Type: application/json
X-Idempotency-Key: UUIDv4

Request Body:
{
  "claimId": "clm_987214",
  "patientId": "pat_001928",
  "stateCode": "CA",
  "billedAmountCents": 550000,
  "emergencyOverride": false,
  "providerTier": "TIER_1"
}

Response (200 OK | 202 Accepted | 422 Unprocessable):
{
  "claimId": "clm_987214",
  "status": "SUSPENDED_REVIEW",
  "reasonCode": "REG_CA_HIGH_DOLLAR_MANDATORY_REVIEW",
  "adjudicatedAmountCents": 0,
  "accumulatorUpdated": true,
  "auditLogId": "aud_882910"
}

• INVARIANT 1 (Atomic Accumulator): Every claim evaluation MUST update the patient YTD accumulator inside an ACID transaction.
• INVARIANT 2 (California State Compliance): Any claim originating from stateCode == "CA" exceeding 500,000 cents ($5,000) WITHOUT emergencyOverride MUST transition to SUSPENDED_REVIEW status.
• INVARIANT 3 (Audit Traceability): Every status transition MUST emit an immutable HIPAA audit event containing operator, timestamp, and rule ID.

• TEST 01 (Golden Master): Submit claimId="clm_ca_01", amount=600000, state="CA" -> Assert status == "SUSPENDED_REVIEW" and accumulator incremented.
• TEST 02 (Override): Submit same claim with emergencyOverride=true -> Assert status == "APPROVED".
• TEST 03 (Idempotency): Re-submitting identical X-Idempotency-Key returns cached response without double-incrementing accumulator.

Self-Assessment: Architect Shift-Left Readiness Checklist (Topic B.4)