How to Use AI to Understand Legacy Code: Walkthrough That Decoded 100K Lines in 3 Days

# My AI Architecture Analysis Prompt Template
find . -name "*.java" -type f | head -20 | xargs wc -l | sort -nr > largest_files.txt

# Then feed this to Claude Code:
"Analyze these 20 largest Java files and create a high-level architecture diagram. 
Focus on:
1. Main application entry points and configuration
2. Core business domain entities and services  
3. External integrations and data persistence layers
4. Authentication and authorization flows
5. Background job processing and scheduled tasks

For each major component, explain:
- Primary responsibility and business purpose
- Key dependencies and integration points  
- Data flow patterns and transformation logic
- Error handling and logging strategies"

# Deep Business Logic Analysis Template
"""
Analyze this [COMPONENT_NAME] and explain:

BUSINESS PURPOSE:
- What real-world business problem does this solve?
- What are the key business rules and constraints?
- How does this component contribute to revenue/customer experience?

TECHNICAL IMPLEMENTATION:
- What are the main classes and their responsibilities?
- How does data flow through this component?
- What external systems or APIs does it integrate with?
- What are the error scenarios and how are they handled?

CRITICAL DEPENDENCIES:
- What other system components does this depend on?
- What happens if those dependencies fail?
- Are there any single points of failure?

MODERNIZATION OPPORTUNITIES:
- What patterns or technologies are outdated?
- Where could we improve performance or maintainability?
- What would be the safest refactoring approach?
"""

/**
 * BUSINESS PURPOSE ANALYSIS (AI Generated):
 * 
 * This PaymentOrchestrator is the heart of revenue generation - it processes
 * $2M monthly in transactions across 8 payment methods. Key business rules:
 * 
 * 1. FRAUD PREVENTION: All transactions >$500 require additional verification
 * 2. MULTI-CURRENCY: Supports 12 currencies with real-time exchange rates  
 * 3. PARTIAL PAYMENTS: Allows installment payments for orders >$200
 * 4. REFUND HANDLING: Automated refund processing within 24 hours
 * 5. COMPLIANCE: PCI DSS compliant with tokenized card storage
 */

@Service
@Transactional
public class PaymentOrchestrator {
    
    /**
     * MAIN PAYMENT WORKFLOW (AI Analysis):
     * 
     * This method orchestrates the complete payment process:
     * 1. Validates payment request and customer eligibility
     * 2. Applies business rules (discounts, taxes, fees)
     * 3. Routes to appropriate payment processor based on method
     * 4. Handles fraud detection and risk assessment  
     * 5. Records transaction and updates order status
     * 6. Triggers downstream notifications and fulfillment
     * 
     * CRITICAL BUSINESS LOGIC:
     * - Orders >$1000 require manager approval (lines 234-267)
     * - International orders have additional verification (lines 456-489)
     * - Subscription payments use stored payment methods (lines 567-623)
     * 
     * IDENTIFIED RISKS:
     * - No timeout handling on external payment gateway calls
     * - Database transaction spans entire method (potential deadlocks)
     * - Hardcoded business rules should be configuration-driven
     */
    public PaymentResult processPayment(PaymentRequest request) {
        
        // AI INSIGHT: This validation logic contains critical business rules
        if (request.getAmount().compareTo(new BigDecimal("1000")) > 0) {
            // BUSINESS RULE: Large transactions need approval
            ApprovalResult approval = approvalService.requestApproval(
                request, ApprovalType.HIGH_VALUE_TRANSACTION
            );
            if (!approval.isApproved()) {
                return PaymentResult.rejected("HIGH_VALUE_APPROVAL_REQUIRED");
            }
        }
        
        // AI INSIGHT: Fraud detection is integrated into payment flow
        FraudAssessment fraudCheck = fraudDetectionEngine.assessTransaction(request);
        if (fraudCheck.getRiskLevel() == RiskLevel.HIGH) {
            // BUSINESS RULE: High-risk transactions are flagged for manual review
            flagForManualReview(request, fraudCheck);
            return PaymentResult.pending("FRAUD_REVIEW_REQUIRED");
        }
        
        // AI INSIGHT: Payment method routing uses strategy pattern
        PaymentProcessor processor = paymentProcessorFactory.getProcessor(
            request.getPaymentMethod()
        );
        
        try {
            // CRITICAL: This is where actual money movement happens
            ProcessorResult result = processor.processPayment(request);
            
            if (result.isSuccessful()) {
                // AI INSIGHT: Success handling includes multiple side effects
                recordTransactionSuccess(request, result);
                updateInventory(request.getOrderId());
                triggerFulfillment(request.getOrderId());
                sendCustomerNotification(request.getCustomerId(), result);
                
                return PaymentResult.success(result.getTransactionId());
            } else {
                // AI INSIGHT: Failure handling preserves audit trail
                recordTransactionFailure(request, result);
                return PaymentResult.failed(result.getErrorCode(), result.getErrorMessage());
            }
            
        } catch (PaymentProcessorException e) {
            // AI INSIGHT: Exception handling lacks retry logic
            log.error("Payment processing failed for order: {}", request.getOrderId(), e);
            recordSystemError(request, e);
            return PaymentResult.error("PAYMENT_SYSTEM_UNAVAILABLE");
        }
    }
}

Based on this codebase analysis, answer these critical questions:

REVENUE & BUSINESS IMPACT:
1. What are the top 3 revenue-generating features?
2. What business rules could affect customer payment success rates?
3. Which components handle refunds and how much manual intervention is required?

OPERATIONAL REQUIREMENTS:  
4. What scheduled jobs run overnight and what do they do?
5. How does the system handle inventory allocation during high traffic?
6. What external services must be available for normal operation?

COMPLIANCE & SECURITY:
7. How is customer PII handled and where is it stored?
8. What audit logging exists for financial transactions?
9. Are there any hardcoded secrets or credentials?

FAILURE SCENARIOS:
10. What happens if the payment gateway goes down?
11. How does the system recover from database connection failures?
12. What manual processes exist for handling edge cases?

# LEGACY SYSTEM BUSINESS INTELLIGENCE ANALYSIS

## 💰 REVENUE & BUSINESS IMPACT

### Top 3 Revenue-Generating Features:
1. **Multi-Payment Gateway Integration** (Lines 1234-2890, PaymentOrchestrator.java)
   - Processes $2M monthly across Credit Cards (60%), PayPal (25%), Bank Transfer (15%)
   - Supports 12 currencies with real-time conversion
   - 97.8% success rate based on transaction logs

2. **Subscription Billing Engine** (Lines 445-1123, SubscriptionManager.java)  
   - Handles $400K monthly recurring revenue
   - Automatic retry logic for failed subscription payments
   - Proration logic for mid-cycle upgrades/downgrades

3. **Dynamic Pricing Engine** (Lines 2234-3456, PricingService.java)
   - Applies discount codes, bulk pricing, customer-specific rates
   - A/B testing framework for pricing optimization
   - Estimated 15% revenue impact through price optimization

### Critical Business Rules Affecting Payment Success:
- **Fraud Threshold**: Transactions >$500 from new customers trigger manual review
- **International Processing**: Non-US orders have 23% higher decline rate due to additional verification
- **Card Retry Logic**: Failed payments retry 3 times over 72 hours before abandonment

## ⚙️ OPERATIONAL REQUIREMENTS

### Overnight Scheduled Jobs:
1. **DailyReportGenerator** (2:00 AM EST) - Generates revenue/inventory reports  
2. **InventoryReorderProcessor** (3:00 AM EST) - Automated purchase order creation
3. **PaymentRetryProcessor** (4:00 AM EST) - Retries failed subscription payments
4. **DataCleanupService** (5:00 AM EST) - Archives old logs and temporary data

### High Traffic Inventory Handling:
- **Pessimistic Locking**: Database-level locks on inventory updates (performance bottleneck)
- **Reserved Inventory**: 15-minute cart reservation system
- **Overselling Prevention**: Real-time inventory checks with fallback to backorder

### External Service Dependencies:
- **CRITICAL**: Stripe, PayPal, Authorize.Net payment gateways
- **HIGH**: FedEx/UPS shipping APIs, TaxJar tax calculation
- **MEDIUM**: SendGrid email, Twilio SMS notifications

## 🔒 COMPLIANCE & SECURITY

### PII Handling:
- Customer data stored in `customers` table with AES-256 encryption
- Credit card data tokenized via payment gateway (no raw storage)  
- **RISK**: Some PII in application logs (needs cleanup)

### Financial Transaction Auditing:
- Complete audit trail in `payment_audit_log` table
- Immutable transaction records with cryptographic signatures
- **COMPLIANCE**: Meets PCI DSS Level 1 requirements

### Security Vulnerabilities Found:
- **CRITICAL**: Hardcoded API keys in DatabaseConfig.java (lines 45-67)
- **HIGH**: SQL injection risk in ReportGenerator.java (lines 234-278)
- **MEDIUM**: Missing rate limiting on login endpoints

## 🚨 FAILURE SCENARIOS

### Payment Gateway Outage:
- **Current**: No circuit breaker pattern - requests timeout after 30 seconds
- **Impact**: 100% payment failure during outage
- **Recovery**: Manual failover to backup gateway (15-minute process)

### Database Connection Failures:
- **Connection Pooling**: HikariCP with 20 max connections
- **Retry Logic**: 3 attempts with exponential backoff
- **Fallback**: Read-only mode using replica database

### Manual Edge Case Processes:
- **Partial Refunds**: Requires database direct access (no UI)
- **Inventory Adjustments**: Manual SQL scripts for discrepancies
- **Customer Account Merging**: 47-step manual process documented in Wiki

#!/usr/bin/env python3
# legacy_code_analyzer.py - AI-powered code analysis

import os
import ast
import json
from pathlib import Path
from collections import defaultdict

class LegacyCodeAnalyzer:
    def __init__(self, project_path):
        self.project_path = Path(project_path)
        self.analysis_results = defaultdict(list)
    
    def analyze_project(self):
        """Analyze entire project for AI processing"""
        
        for file_path in self.project_path.rglob("*.py"):
            if self._should_analyze_file(file_path):
                analysis = self._analyze_file(file_path)
                self.analysis_results[str(file_path)] = analysis
        
        return self._generate_ai_prompt()
    
    def _analyze_file(self, file_path):
        """Extract key metrics from individual file"""
        
        try:
            with open(file_path, 'r', encoding='utf-8') as f:
                content = f.read()
                tree = ast.parse(content)
            
            analysis = {
                'line_count': len(content.splitlines()),
                'function_count': len([n for n in ast.walk(tree) if isinstance(n, ast.FunctionDef)]),
                'class_count': len([n for n in ast.walk(tree) if isinstance(n, ast.ClassDef)]),
                'complexity_indicators': self._calculate_complexity(tree),
                'imports': self._extract_imports(tree),
                'docstring_coverage': self._check_documentation(tree)
            }
            
            return analysis
            
        except Exception as e:
            return {'error': str(e)}
    
    def _calculate_complexity(self, tree):
        """Calculate complexity indicators for AI analysis"""
        
        complexity_metrics = {
            'nested_loops': 0,
            'conditional_depth': 0,
            'try_except_blocks': 0,
            'large_functions': []
        }
        
        for node in ast.walk(tree):
            if isinstance(node, ast.For) or isinstance(node, ast.While):
                # Count nested loops
                nested_count = len([n for n in ast.walk(node) if isinstance(n, (ast.For, ast.While))])
                complexity_metrics['nested_loops'] = max(complexity_metrics['nested_loops'], nested_count)
            
            elif isinstance(node, ast.FunctionDef):
                # Identify large functions
                func_lines = node.end_lineno - node.lineno if hasattr(node, 'end_lineno') else 0
                if func_lines > 50:
                    complexity_metrics['large_functions'].append({
                        'name': node.name,
                        'lines': func_lines,
                        'args_count': len(node.args.args)
                    })
        
        return complexity_metrics
    
    def _generate_ai_prompt(self):
        """Generate comprehensive prompt for AI analysis"""
        
        # Sort files by complexity for priority analysis
        complex_files = sorted(
            self.analysis_results.items(),
            key=lambda x: x[1].get('line_count', 0),
            reverse=True
        )[:10]
        
        prompt = f"""
        Analyze this legacy codebase with {len(self.analysis_results)} files:
        
        TOP COMPLEX FILES FOR PRIORITY ANALYSIS:
        """
        
        for file_path, analysis in complex_files:
            prompt += f"""
        FILE: {file_path}
        - Lines: {analysis.get('line_count', 0)}
        - Functions: {analysis.get('function_count', 0)}
        - Classes: {analysis.get('class_count', 0)}
        - Large Functions: {len(analysis.get('complexity_indicators', {}).get('large_functions', []))}
        """
        
        prompt += """
        
        Please provide:
        1. High-level architecture overview
        2. Business logic patterns and purposes
        3. Critical dependencies and integration points
        4. Security and performance risks
        5. Modernization recommendations
        6. Refactoring priority order
        """
        
        return prompt

if __name__ == "__main__":
    analyzer = LegacyCodeAnalyzer("/path/to/legacy/project")
    ai_prompt = analyzer.analyze_project()
    print(ai_prompt)