Migration Planning

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102

// Example: Service Inventory Data Structure
interface ServiceCandidate {
  id: string;
  name: string;
  businessDomain: string;
  
  // Business context
  description: string;
  businessOwner: string;
  criticalityLevel: 'critical' | 'high' | 'medium' | 'low';
  revenueImpact: 'direct' | 'indirect' | 'none';
  
  // Technical mapping
  codeModules: CodeModule[];
  dataEntities: DataEntity[];
  externalDependencies: ExternalSystem[];
  
  // Ownership
  owningTeam: string;
  contributingTeams: string[];
  domainExperts: string[];
  
  // Current state metrics
  changeFrequency: 'daily' | 'weekly' | 'monthly' | 'quarterly';
  incidentFrequency: number; // per quarter
  technicalDebtScore: number; // 1-10
  testCoveragePercent: number;
  
  // Migration considerations
  extractionComplexity: 'low' | 'medium' | 'high' | 'extreme';
  estimatedEffortWeeks: number;
  riskFactors: string[];
}
 
interface CodeModule {
  path: string;
  linesOfCode: number;
  language: string;
  age: Date;
  lastModified: Date;
  contributors: string[];
}
 
interface DataEntity {
  name: string;
  tableName: string;
  rowCount: number;
  sizeGB: number;
  ownershipType: 'owns' | 'reads' | 'writes' | 'shared';
  referencedBy: string[]; // other service candidate IDs
}
 
// Example inventory entry
const userManagementService: ServiceCandidate = {
  id: 'svc-user-management',
  name: 'User Management',
  businessDomain: 'Identity & Access',
  description: 'Handles user registration, authentication, profile management, and access control',
  businessOwner: 'Head of Product',
  criticalityLevel: 'critical',
  revenueImpact: 'indirect',
  
  codeModules: [
    { path: 'src/auth/*', linesOfCode: 12500, language: 'Java', 
      age: new Date('2018-03-15'), lastModified: new Date('2024-01-10'),
      contributors: ['alice', 'bob', 'charlie'] },
    { path: 'src/users/*', linesOfCode: 8200, language: 'Java',
      age: new Date('2017-06-22'), lastModified: new Date('2024-01-12'),
      contributors: ['alice', 'diana'] },
  ],
  
  dataEntities: [
    { name: 'User', tableName: 'users', rowCount: 2500000, sizeGB: 4.2,
      ownershipType: 'owns', referencedBy: ['svc-orders', 'svc-payments', 'svc-audit'] },
    { name: 'Role', tableName: 'roles', rowCount: 150, sizeGB: 0.001,
      ownershipType: 'owns', referencedBy: ['svc-admin', 'svc-audit'] },
    { name: 'Permission', tableName: 'permissions', rowCount: 500, sizeGB: 0.002,
      ownershipType: 'owns', referencedBy: ['svc-admin'] },
  ],
  
  externalDependencies: [
    { name: 'OAuth Provider', type: 'identity' },
    { name: 'Email Service', type: 'notification' },
  ],
  
  owningTeam: 'Platform Team',
  contributingTeams: ['Security Team', 'Mobile Team'],
  domainExperts: ['Alice (auth)', 'Bob (security)'],
  
  changeFrequency: 'weekly',
  incidentFrequency: 2,
  technicalDebtScore: 6,
  testCoveragePercent: 72,
  
  extractionComplexity: 'high',
  estimatedEffortWeeks: 16,
  riskFactors: [
    'Central dependency for all other services',
    'Active session management complexity',
    'Token format used across entire system',
  ],
};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116

// Dependency Graph Analysis for Migration Planning
 
interface DependencyNode {
  serviceId: string;
  afferentCoupling: number;  // incoming dependencies (fan-in)
  efferentCoupling: number;  // outgoing dependencies (fan-out)
}
 
interface DependencyEdge {
  from: string;
  to: string;
  type: 'code' | 'data' | 'event' | 'state' | 'timing';
  strength: 'weak' | 'strong' | 'critical';
  frequency: number; // calls per minute in production
}
 
class DependencyAnalyzer {
  private nodes: Map<string, DependencyNode> = new Map();
  private edges: DependencyEdge[] = [];
  
  // Calculate instability: ratio of outgoing to total dependencies
  // High instability (close to 1) = depends on many, few depend on it
  // Low instability (close to 0) = few outgoing deps, many incoming
  calculateInstability(serviceId: string): number {
    const node = this.nodes.get(serviceId);
    if (!node) return 0;
    const total = node.afferentCoupling + node.efferentCoupling;
    return total === 0 ? 0 : node.efferentCoupling / total;
  }
  
  // Find services that would be easiest to extract (leaf nodes)
  findExtractionCandidates(): string[] {
    return Array.from(this.nodes.entries())
      .filter(([_, node]) => node.afferentCoupling === 0) // nothing depends on it
      .sort((a, b) => a[1].efferentCoupling - b[1].efferentCoupling) // fewest outgoing deps first
      .map(([id]) => id);
  }
  
  // Find core services that everything depends on (extract last)
  findCoreServices(): string[] {
    const avgAfferent = Array.from(this.nodes.values())
      .reduce((sum, n) => sum + n.afferentCoupling, 0) / this.nodes.size;
    
    return Array.from(this.nodes.entries())
      .filter(([_, node]) => node.afferentCoupling > avgAfferent * 2)
      .map(([id]) => id);
  }
  
  // Detect dependency cycles (problematic for extraction)
  detectCycles(): string[][] {
    const cycles: string[][] = [];
    const visited = new Set<string>();
    const recursionStack = new Set<string>();
    
    const dfs = (nodeId: string, path: string[]): void => {
      visited.add(nodeId);
      recursionStack.add(nodeId);
      
      const outgoing = this.edges
        .filter(e => e.from === nodeId)
        .map(e => e.to);
      
      for (const neighbor of outgoing) {
        if (!visited.has(neighbor)) {
          dfs(neighbor, [...path, nodeId]);
        } else if (recursionStack.has(neighbor)) {
          // Found cycle
          const cycleStart = path.indexOf(neighbor);
          cycles.push(path.slice(cycleStart));
        }
      }
      
      recursionStack.delete(nodeId);
    };
    
    for (const nodeId of this.nodes.keys()) {
      if (!visited.has(nodeId)) {
        dfs(nodeId, []);
      }
    }
    
    return cycles;
  }
  
  // Calculate extraction order minimizing cross-cutting changes
  calculateExtractionOrder(): string[] {
    const order: string[] = [];
    const remaining = new Set(this.nodes.keys());
    const extracted = new Set<string>();
    
    while (remaining.size > 0) {
      // Find node with fewest dependencies on remaining nodes
      let bestCandidate: string | null = null;
      let bestScore = Infinity;
      
      for (const nodeId of remaining) {
        const depsOnRemaining = this.edges
          .filter(e => e.from === nodeId && remaining.has(e.to))
          .length;
        
        if (depsOnRemaining < bestScore) {
          bestScore = depsOnRemaining;
          bestCandidate = nodeId;
        }
      }
      
      if (bestCandidate) {
        order.push(bestCandidate);
        remaining.delete(bestCandidate);
        extracted.add(bestCandidate);
      }
    }
    
    return order;
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102

// Comprehensive Complexity Scoring System
 
interface ComplexityDimension {
  name: string;
  weight: number;  // relative importance (0-1)
  score: number;   // assessed difficulty (1-10)
  rationale: string;
}
 
interface ComplexityAssessment {
  serviceId: string;
  assessedDate: Date;
  assessedBy: string[];
  
  dimensions: ComplexityDimension[];
  
  // Calculated fields
  weightedScore: number;
  confidenceLevel: 'low' | 'medium' | 'high';
  riskFlags: string[];
}
 
function calculateComplexityScore(dimensions: ComplexityDimension[]): number {
  const totalWeight = dimensions.reduce((sum, d) => sum + d.weight, 0);
  const weightedSum = dimensions.reduce((sum, d) => sum + d.score * d.weight, 0);
  return Math.round((weightedSum / totalWeight) * 10) / 10;
}
 
// Example assessment for Order Processing service
const orderProcessingComplexity: ComplexityAssessment = {
  serviceId: 'svc-order-processing',
  assessedDate: new Date('2024-01-15'),
  assessedBy: ['Tech Lead', 'Architect', 'Product Owner'],
  
  dimensions: [
    {
      name: 'Code Coupling',
      weight: 0.15,
      score: 8,
      rationale: 'Order processing touches inventory, payments, shipping, notifications, and analytics. Over 200 cross-module dependencies identified.',
    },
    {
      name: 'Data Coupling',
      weight: 0.20,
      score: 9,
      rationale: 'Orders table has foreign keys to users, products, inventory, payments. Single transactions update 6 tables across 3 bounded contexts.',
    },
    {
      name: 'Team Complexity',
      weight: 0.10,
      score: 6,
      rationale: 'Primarily owned by Order Team, but Payments Team and Inventory Team make regular changes.',
    },
    {
      name: 'Business Logic Complexity',
      weight: 0.15,
      score: 9,
      rationale: 'Complex state machine with 14 states. Pricing rules, discount application, tax calculation, inventory reservation logic all embedded.',
    },
    {
      name: 'External Integrations',
      weight: 0.10,
      score: 7,
      rationale: 'Integrates with 3 payment providers, 4 shipping carriers, tax calculation API, fraud detection service.',
    },
    {
      name: 'Performance Criticality',
      weight: 0.15,
      score: 9,
      rationale: 'Checkout latency directly impacts conversion. Current p99 latency: 450ms. Business requires < 500ms p99.',
    },
    {
      name: 'Data Volume',
      weight: 0.10,
      score: 8,
      rationale: '85GB current data. 250K orders/day. Black Friday peaks at 1.5M orders. Requires careful data migration.',
    },
    {
      name: 'Test Coverage',
      weight: 0.05,
      score: 5,
      rationale: '68% unit test coverage. Integration tests exist but are flaky. No contract tests for downstream consumers.',
    },
  ],
  
  weightedScore: 7.9, // Calculated
  confidenceLevel: 'medium',
  riskFlags: [
    'Data coupling score > 8: requires extensive data migration planning',
    'Business logic score > 8: high regression risk during extraction',
    'Performance criticality > 8: cannot tolerate latency increases during migration',
  ],
};
 
// Complexity categories for prioritization
function categorizeComplexity(score: number): string {
  if (score <= 3) return 'Quick Win';
  if (score <= 5) return 'Moderate Effort';
  if (score <= 7) return 'Significant Investment';
  if (score <= 8.5) return 'Major Initiative';
  return 'Strategic Program';
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115

// Business Value Assessment Framework
 
interface BusinessValueDimension {
  name: string;
  weight: number;
  score: number;  // 1-10
  quantification?: string;  // Measurable impact when possible
}
 
interface BusinessValueAssessment {
  serviceId: string;
  dimensions: BusinessValueDimension[];
  totalValueScore: number;
  strategicAlignment: 'critical' | 'important' | 'nice-to-have';
  timeToValue: 'immediate' | 'short-term' | 'long-term';
}
 
// Example: Notification Service Value Assessment
const notificationServiceValue: BusinessValueAssessment = {
  serviceId: 'svc-notifications',
  dimensions: [
    {
      name: 'Development Velocity',
      weight: 0.20,
      score: 9,
      quantification: 'Currently 3-week release cycle due to monolith deployment. Independent service could deploy daily.',
    },
    {
      name: 'Independent Scalability',
      weight: 0.15,
      score: 8,
      quantification: 'Notification volume is 50x user requests. Currently over-provisioning entire monolith for notification load.',
    },
    {
      name: 'Technology Modernization',
      weight: 0.10,
      score: 7,
      quantification: 'Can migrate from synchronous email sending to async queue-based processing with modern event streaming.',
    },
    {
      name: 'Team Autonomy',
      weight: 0.15,
      score: 9,
      quantification: 'Communications team currently blocked by platform team for 40% of sprints.',
    },
    {
      name: 'Reliability Improvement',
      weight: 0.20,
      score: 8,
      quantification: 'Email service timeouts cause 12% of checkout abandonment. Async decoupling eliminates this.',
    },
    {
      name: 'Cost Optimization',
      weight: 0.10,
      score: 6,
      quantification: 'Estimated $45K/month savings from right-sizing notification infrastructure independently.',
    },
    {
      name: 'Strategic Enablement',
      weight: 0.10,
      score: 7,
      quantification: 'Enables B2B notification API for enterprise customers - $2M ARR opportunity.',
    },
  ],
  totalValueScore: 7.9,
  strategicAlignment: 'critical',
  timeToValue: 'short-term',
};
 
// Value-Complexity Matrix Calculation
interface PrioritizationQuadrant {
  name: string;
  services: string[];
  recommendation: string;
}
 
function calculateValueComplexityMatrix(
  valueScores: Map<string, number>,
  complexityScores: Map<string, number>
): PrioritizationQuadrant[] {
  const services = Array.from(valueScores.keys());
  const avgValue = Array.from(valueScores.values()).reduce((a, b) => a + b, 0) / services.length;
  const avgComplexity = Array.from(complexityScores.values()).reduce((a, b) => a + b, 0) / services.length;
  
  return [
    {
      name: 'Quick Wins (High Value, Low Complexity)',
      services: services.filter(s => 
        valueScores.get(s)! > avgValue && complexityScores.get(s)! < avgComplexity
      ),
      recommendation: 'Prioritize immediately. These deliver maximum ROI.',
    },
    {
      name: 'Strategic Bets (High Value, High Complexity)',
      services: services.filter(s => 
        valueScores.get(s)! > avgValue && complexityScores.get(s)! >= avgComplexity
      ),
      recommendation: 'Plan carefully. Worth the investment but requires significant resources.',
    },
    {
      name: 'Incremental Improvements (Low Value, Low Complexity)',
      services: services.filter(s => 
        valueScores.get(s)! <= avgValue && complexityScores.get(s)! < avgComplexity
      ),
      recommendation: 'Consider for team skill building or when resources available.',
    },
    {
      name: 'Avoid (Low Value, High Complexity)',
      services: services.filter(s => 
        valueScores.get(s)! <= avgValue && complexityScores.get(s)! >= avgComplexity
      ),
      recommendation: 'Do not extract unless circumstances change significantly.',
    },
  ];
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74

// Weighted Shortest Job First (WSJF) for Migration Prioritization
 
interface WSJFScoring {
  serviceId: string;
  
  // Cost of Delay components
  businessValue: number;        // 1-10: Value delivered when extracted
  timeCriticality: number;      // 1-10: Urgency (regulatory, competitive, etc.)
  riskReductionOpportunity: number;  // 1-10: Risk/problem reduction
  
  // Job Size
  extractionEffort: number;     // 1-10: T-shirt sized effort
  
  // Calculated
  costOfDelay: number;
  wsjfScore: number;
}
 
function calculateWSJF(scoring: WSJFScoring): number {
  // Cost of Delay = Business Value + Time Criticality + Risk Reduction
  const costOfDelay = scoring.businessValue + scoring.timeCriticality + 
                      scoring.riskReductionOpportunity;
  
  // WSJF = Cost of Delay / Job Size
  // Higher score = Should be done earlier
  return costOfDelay / scoring.extractionEffort;
}
 
// Example prioritization
const servicePriorities: WSJFScoring[] = [
  {
    serviceId: 'svc-notifications',
    businessValue: 8,
    timeCriticality: 5,
    riskReductionOpportunity: 9,  // High - causes checkout failures
    extractionEffort: 3,          // Relatively isolated
    costOfDelay: 22,
    wsjfScore: 7.33,  // HIGH PRIORITY
  },
  {
    serviceId: 'svc-order-processing',
    businessValue: 9,
    timeCriticality: 7,
    riskReductionOpportunity: 8,
    extractionEffort: 9,          // Very complex
    costOfDelay: 24,
    wsjfScore: 2.67,  // LOWER PRIORITY (high effort)
  },
  {
    serviceId: 'svc-product-catalog',
    businessValue: 6,
    timeCriticality: 4,
    riskReductionOpportunity: 3,
    extractionEffort: 4,
    costOfDelay: 13,
    wsjfScore: 3.25,  // MODERATE
  },
  {
    serviceId: 'svc-analytics',
    businessValue: 5,
    timeCriticality: 2,
    riskReductionOpportunity: 2,
    extractionEffort: 2,          // Easy - mostly reads
    costOfDelay: 9,
    wsjfScore: 4.50,  // GOOD QUICK WIN
  },
];
 
// Sort by WSJF score descending for priority order
const priorityOrder = servicePriorities
  .sort((a, b) => b.wsjfScore - a.wsjfScore)
  .map(s => s.serviceId);
 
// Result: ['svc-notifications', 'svc-analytics', 'svc-product-catalog', 'svc-order-processing']

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66

# Migration Assessment Summary
## Executive Overview
 
**Assessment Completed**: January 2024
**Scope**: E-Commerce Platform Monolith → Microservices
**Recommendation**: Proceed with phased migration over 24 months
 
## Current State
 
- **Monolith Age**: 8 years
- **Lines of Code**: 850,000
- **Database Size**: 2.3TB across 340 tables
- **Daily Transactions**: 1.2M
- **Annual Revenue Processed**: $180M
 
## Service Inventory Summary
 
| Category | Count | Avg Complexity | Avg Value |
|----------|-------|----------------|-----------|
| Core Commerce | 6 | 7.8 | 8.5 |
| Supporting | 8 | 4.2 | 5.8 |
| Generic | 4 | 2.5 | 3.2 |
| **Total** | **18** | **5.1** | **6.0** |
 
## Recommended Extraction Sequence
 
### Phase 1: Foundation (Months 1-6)
- **Goal**: Build capabilities, early wins
- Notifications Service (WSJF: 7.33)
- Analytics Service (WSJF: 4.50)
- **Investment**: 2 teams, $400K
- **Expected Value**: 15% deployment frequency increase
 
### Phase 2: Growth (Months 7-14)
- **Goal**: Strategic value delivery  
- Product Catalog Service
- Inventory Service
- Search Service
- **Investment**: 3 teams, $800K
- **Expected Value**: Independent scaling, 25% infra cost reduction
 
### Phase 3: Core (Months 15-24)
- **Goal**: Complete decoupling
- Order Processing (complex)
- Payment Processing
- User Management
- **Investment**: 4 teams, $1.2M
- **Expected Value**: Full team autonomy, 50% faster feature delivery
 
## Key Risks
 
1. **Data Coupling** (High): 47% of services share data dependencies
   - Mitigation: Event-driven synchronization, phased data migration
   
2. **Skills Gap** (Medium): Limited distributed systems experience
   - Mitigation: Training program, external consulting for Phase 1
 
3. **Executive Patience** (Medium): 24-month timeline may face pressure
   - Mitigation: Quarterly value demonstrations, metrics dashboard
 
## Success Metrics
 
- [ ] 2x deployment frequency by Month 12
- [ ] 30% reduction in incident MTTR by Month 18
- [ ] Zero monolith deployments required for new features by Month 24
- [ ] 15% infrastructure cost reduction through independent scaling