System Design (HLD)Migration Planning

Migration Planning

LevelAdvanced

Duration75 mins

TopicMigration Planning

1 / 5

Assessment and Prioritization

The Foundation of Every Successful Migration

The graveyard of failed microservices migrations is vast. Industry studies suggest that 60-70% of migration initiatives either fail outright or deliver far less value than anticipated. The pattern is painfully consistent: organizations rush into extraction without proper assessment, prioritize based on political convenience rather than strategic value, and find themselves years later maintaining both a legacy monolith and a constellation of poorly-designed services.

What separates successful migrations from expensive failures isn't technical brilliance—it's methodical assessment and disciplined prioritization. Before writing a single line of migration code, elite engineering organizations invest significant effort understanding exactly what they're migrating, why each component matters, and in what order extraction will deliver maximum value with minimum risk.

What You'll Learn

This page teaches the systematic approach to migration assessment used by organizations like Amazon, Netflix, and Uber during their transformational migrations. You'll learn to create comprehensive service inventories, map complex dependencies, score migration complexity, assess business value, evaluate organizational readiness, and apply sophisticated prioritization frameworks that balance risk, value, and technical feasibility.

The Case for Rigorous Assessment

Many organizations approach migration with a dangerously simplistic model: "We'll just break apart the monolith piece by piece." This view fundamentally misunderstands the complexity of established systems. A monolith that has been in production for years is not a neatly organized collection of independent modules—it's an ecosystem of interconnected components, implicit contracts, hidden dependencies, and accumulated business logic that often exists only in the code.

Why Assessment Is Non-Negotiable:

The Hidden Complexity Problem

•Invisible Dependencies: Code analysis alone reveals only explicit dependencies. Implicit dependencies—shared database tables, in-memory state, timing assumptions, event ordering—are often undocumented and discovered only during extraction.
•Business Logic Dispersion: Critical business rules are rarely contained in single modules. They spread across layers: validation in the UI, enforcement in middleware, additional checks in database triggers. Extracting one component without understanding this dispersion creates subtle bugs.
•Performance Coupling: Monoliths often achieve performance through in-process calls and shared caches. Converting these to network calls and distributed caches can introduce latency and consistency issues that weren't visible in the original design.
•Organizational Knowledge Distribution: Understanding of system behavior often exists only in the minds of specific engineers. Assessment captures this knowledge before migration disrupts team structures.

The Cost of Skipping Assessment

A major e-commerce company attempted to extract their payment processing into a microservice without proper assessment. They discovered mid-migration that payment logic was intertwined with order management, inventory, fraud detection, and tax calculation through 47 different code paths. The extraction took 18 months instead of the planned 3, required rewrites of 5 additional components, and caused 3 production incidents impacting $4.2M in transactions.

Building the Service Inventory

A service inventory is a comprehensive catalog of all functional capabilities within your monolith that could potentially become independent services. This isn't a code-level analysis—it's a business-capability-level mapping that identifies natural service boundaries based on domain concepts rather than current code organization.

The Inventory Process:

Service Inventory Framework

•Domain Mapping: Start with business domains, not code. Identify core business capabilities: user management, product catalog, order processing, payment handling, inventory management, shipping, analytics, etc.
•Code Correlation: Map each business capability to the code components that implement it. A single capability may span multiple code modules; a single module may implement multiple capabilities.
•Data Ownership Analysis: For each capability, identify what data it owns (creates/updates as source of truth) versus what data it reads from other capabilities.
•Interface Documentation: Document all interfaces each capability exposes (APIs, events, database views) and consumes (API calls, event subscriptions, database queries).
•Team Ownership Recording: Note which team(s) currently own each capability. Multiple teams sharing a capability indicates potential extraction complexity.

ServiceInventory.ts
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',
  ],
};

Pro Strategy: Workshop-Based Inventory

The most effective inventories emerge from cross-functional workshops, not isolated technical analysis. Bring together engineering leads, product managers, and business stakeholders. Engineers understand technical boundaries; product managers understand feature groupings; business stakeholders understand value streams. The intersection produces service candidates that align with business reality, not just code organization.

Dependency Mapping and Analysis

Dependencies are the primary source of migration complexity. A thorough dependency analysis reveals the true interconnectedness of your system and identifies which extractions are straightforward versus which will propagate changes across the codebase.

Types of Dependencies to Identify:

Dependency Taxonomy for Migration Assessment
Dependency Type	Description	Detection Method	Migration Impact
Code Dependencies	Direct function/method calls, class inheritance, interface implementations	Static code analysis, import graphs	Must be replaced with API calls or shared libraries
Data Dependencies	Shared database tables, foreign key relationships, transaction scope	Schema analysis, query logs	Requires data migration strategy, API-based access, or eventual consistency
Event Dependencies	In-process event handlers, observer patterns, callbacks	Code analysis, runtime tracing	Must become distributed events with delivery guarantees
State Dependencies	Shared in-memory caches, session state, thread-local data	Runtime analysis, profiling	Requires externalized state management (Redis, etc.)
Timing Dependencies	Assumed ordering of operations, synchronous expectations	Transaction analysis, integration tests	Requires explicit coordination or saga patterns
Contract Dependencies	Implicit API contracts, assumed data formats, version expectations	Interface documentation, consumer analysis	Requires explicit versioning and contract testing

Dependency Graph Construction:

Visualizing dependencies as a directed graph reveals critical patterns:

DependencyGraph.ts
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;
  }
}

Runtime vs Static Analysis

Static code analysis reveals explicit dependencies, but production runtime analysis reveals actual usage patterns. A function may be technically dependent on another, but if it's called once per week while another is called 10,000 times per minute, their migration implications are radically different. Instrument your production environment to capture call graphs, frequency, and latency characteristics.

Complexity Scoring

Not all services are equally difficult to extract. A rigorous complexity scoring system quantifies extraction difficulty, enabling informed prioritization decisions and accurate effort estimation.

Multi-Dimensional Complexity Assessment:

Complexity Scoring Dimensions
Dimension	Low (1-3)	Medium (4-6)	High (7-10)
Code Coupling	Isolated module with clear interfaces	Some shared utilities, moderate coupling	Deep entanglement with multiple modules
Data Coupling	Own tables, no foreign keys to other domains	Some shared lookup tables	Transactions span multiple domains
Team Complexity	Single team owns entirely	2-3 teams contribute occasionally	Shared ownership across 4+ teams
Business Logic Complexity	Simple CRUD operations	Moderate business rules	Complex workflows, state machines
External Integrations	No external systems	1-2 external APIs or services	Multiple external dependencies
Performance Criticality	Background processing, tolerant of latency	User-facing, moderate SLAs	Real-time, strict latency requirements
Data Volume	< 1GB, < 10K transactions/day	1-100GB, 10K-1M transactions/day	100GB, > 1M transactions/day
Test Coverage	80% coverage, comprehensive integration tests	50-80% coverage, basic integration tests	< 50% coverage, minimal testing

ComplexityScoring.ts
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';
}

Calibration Through Experience

Complexity scoring improves dramatically after extracting your first few services. Use early extractions to calibrate your scoring model—compare estimated complexity against actual effort. Most organizations find they consistently underestimate data coupling and business logic complexity while overestimating code coupling difficulty.

Business Value Assessment

Technical complexity tells half the story. The other half is business value—the benefit the organization receives from successfully extracting a service. Prioritization requires balancing both dimensions.

Value Dimensions to Consider:

Business Value Categories

•Development Velocity Impact: How much faster could the team ship features if this component were independent? Measure by release frequency and lead time.
•Scalability Requirements: Does this component need to scale independently? Components with traffic 10x higher than the rest of the system are strong candidates.
•Technology Modernization: Does extraction enable migration from legacy technology (outdated frameworks, unsupported languages) to modern stacks?
•Team Autonomy: Will extraction allow a team to work independently without coordinating deployments with other teams?
•Reliability Improvement: Is this component a frequent source of incidents? Would isolation prevent cascading failures?
•Cost Optimization: Can independent scaling reduce infrastructure costs? Components that over-provision for peak loads benefit from isolation.
•Strategic Enablement: Does extraction enable new business capabilities (B2B APIs, partner integrations, new product lines)?

BusinessValueAssessment.ts
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.',
    },
  ];
}

Quantify When Possible

Abstract value scores are useful for relative comparison, but specific quantification strengthens business cases. 'Improves reliability' is less compelling than 'Eliminates the source of 23% of P1 incidents, reducing annual incident response costs by $180K.' Work with product managers and finance to attach numbers wherever possible.

Organizational Readiness Assessment

Technical and business assessments are necessary but not sufficient. Migration success also depends on organizational factors: team skills, cultural readiness, operational capability, and executive support.

Readiness Dimensions:

Organizational Readiness Assessment Matrix
Dimension	Questions to Answer	Green Flags	Red Flags
Distributed Systems Skills	Does the team understand eventual consistency, network partitions, and distributed debugging?	Team has built/operated distributed systems before; training programs in place	Team only knows monolithic patterns; no distributed systems experience
DevOps Maturity	Can teams independently build, test, deploy, and monitor services?	CI/CD pipelines, infrastructure-as-code, observability stack in place	Manual deployments, shared environments, insufficient monitoring
Operational Capabilities	Who will operate services at 3 AM? Is there on-call structure?	Team-based on-call, runbooks, incident response processes defined	Central ops team handles everything; no per-team ownership
Cultural Alignment	Do teams embrace ownership? Are they willing to learn new approaches?	Strong ownership culture, growth mindset, experimentation encouraged	Blame culture, change-averse, 'not my job' mentality
Executive Support	Is leadership committed to the multi-year journey?	Clear budget commitment, migration metrics in OKRs, visible sponsorship	Migration competes with features; sponsor unclear; funding uncertain
Platform Capabilities	Does platform support service independence (container orchestration, service mesh, observability)?	Kubernetes, service mesh, centralized logging/tracing operational	Manual VM provisioning, no container support, limited observability

Common Organizational Readiness Gaps

•Testing Gap: Teams accustomed to integration tests within monolith lack experience with contract testing, consumer-driven contracts, and distributed test strategies.
•Monitoring Gap: Monolith monitoring focuses on single-system metrics. Distributed tracing, cross-service correlation, and business transaction monitoring require new skills.
•Data Management Gap: Teams familiar with transactions within single databases need training on eventual consistency, saga patterns, and distributed data management.
•Ownership Gap: In monoliths, shared ownership is common. Microservices demand clear ownership—teams must own build, deploy, and operate.
•Communication Gap: Independent services require explicit communication (APIs, events). Teams must learn contract definition, versioning, and backward compatibility.

Address Readiness Before Extraction

Significant readiness gaps should be addressed before major extractions begin. Start with a platform capability initiative, training programs, and pilot projects that build skills without high-stakes pressure. Attempting complex extractions with unprepared teams creates painful failures that undermine future migration efforts.

Prioritization Frameworks

With inventory, dependencies, complexity, value, and readiness assessed, you can now apply structured prioritization frameworks to sequence your migration. Different frameworks suit different contexts.

The WSJF (Weighted Shortest Job First) Approach:

PrioritizationFrameworks.ts
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']

Alternative Prioritization Strategies:

Strategic Prioritization Approaches

•Strangler Sequence: Start with edge services (APIs, UI backends), work inward toward core. Each extraction reduces monolith surface area while core remains stable.
•Pain-Driven: Extract the most problematic components first—those causing incidents, blocking releases, or frustrating teams. High risk but high impact.
•Skill-Building: Start with simple extractions to build team capability, then tackle complex components when skills are proven.
•Business-Aligned: Prioritize by product roadmap. Extract components that need features first, maintaining velocity on strategic initiatives.
•Dependency-Ordered: Use topological sort on dependency graph. Extract leaf nodes first, working toward core services that everything depends on.
•Team-Based: Assign each team a component to extract in parallel, maximizing throughput while matching domain expertise.

Combine Approaches

The most effective prioritization combines multiple factors. Use WSJF for overall ranking, but apply dependency constraints (can't extract A before B), organizational constraints (team availability), and strategic windows (align with product releases). The goal is a sequence that's both optimal and executable.

Documenting and Communicating Assessment

A thorough assessment is worthless if it lives only in the heads of those who conducted it. Proper documentation serves multiple purposes: it creates organizational alignment, enables informed decision-making by leadership, provides a reference during execution, and captures institutional knowledge that outlasts individual contributors.

Key Documentation Artifacts:

Assessment Documentation Suite

•Service Inventory Catalog: Living document listing all service candidates with ownership, complexity scores, value scores, and current status. Update as assessment evolves.
•Dependency Map Visualization: Graph visualization showing service interdependencies. Both high-level (service-to-service) and detailed (specific integration points) views.
•Migration Readiness Report: Summary of organizational readiness with identified gaps, remediation plans, and timeline for addressing prerequisites.
•Prioritized Migration Roadmap: Sequenced list of extraction targets with estimated effort, dependencies, team assignments, and expected value delivery.
•Risk Register: Enumeration of identified risks with likelihood, impact, mitigation strategies, and owners. Updated throughout migration.
•Decision Log: Record of key decisions made during assessment, including alternatives considered and rationale for choices. Invaluable for future teams.
•Business Case Summary: Executive-friendly document summarizing investment required, value to be delivered, timeline, and success metrics.

MigrationAssessmentSummary.md
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

Assessment Complete

You now have the framework for conducting rigorous migration assessments. The next page explores team structure considerations—how to organize engineering teams for successful migration execution and long-term microservices ownership.

1 / 5

Loading learning content...

System Design (HLD)Migration Planning

Migration Planning

LevelAdvanced

Duration75 mins

TopicMigration Planning

1 / 5

Assessment and Prioritization

The Foundation of Every Successful Migration

What You'll Learn

The Case for Rigorous Assessment

Why Assessment Is Non-Negotiable:

The Hidden Complexity Problem

•Invisible Dependencies: Code analysis alone reveals only explicit dependencies. Implicit dependencies—shared database tables, in-memory state, timing assumptions, event ordering—are often undocumented and discovered only during extraction.
•Business Logic Dispersion: Critical business rules are rarely contained in single modules. They spread across layers: validation in the UI, enforcement in middleware, additional checks in database triggers. Extracting one component without understanding this dispersion creates subtle bugs.
•Performance Coupling: Monoliths often achieve performance through in-process calls and shared caches. Converting these to network calls and distributed caches can introduce latency and consistency issues that weren't visible in the original design.
•Organizational Knowledge Distribution: Understanding of system behavior often exists only in the minds of specific engineers. Assessment captures this knowledge before migration disrupts team structures.

The Cost of Skipping Assessment

Building the Service Inventory

The Inventory Process:

Service Inventory Framework

•Domain Mapping: Start with business domains, not code. Identify core business capabilities: user management, product catalog, order processing, payment handling, inventory management, shipping, analytics, etc.
•Code Correlation: Map each business capability to the code components that implement it. A single capability may span multiple code modules; a single module may implement multiple capabilities.
•Data Ownership Analysis: For each capability, identify what data it owns (creates/updates as source of truth) versus what data it reads from other capabilities.
•Interface Documentation: Document all interfaces each capability exposes (APIs, events, database views) and consumes (API calls, event subscriptions, database queries).
•Team Ownership Recording: Note which team(s) currently own each capability. Multiple teams sharing a capability indicates potential extraction complexity.

ServiceInventory.ts
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',
  ],
};

Pro Strategy: Workshop-Based Inventory

Dependency Mapping and Analysis

Types of Dependencies to Identify:

Dependency Taxonomy for Migration Assessment
Dependency Type	Description	Detection Method	Migration Impact
Code Dependencies	Direct function/method calls, class inheritance, interface implementations	Static code analysis, import graphs	Must be replaced with API calls or shared libraries
Data Dependencies	Shared database tables, foreign key relationships, transaction scope	Schema analysis, query logs	Requires data migration strategy, API-based access, or eventual consistency
Event Dependencies	In-process event handlers, observer patterns, callbacks	Code analysis, runtime tracing	Must become distributed events with delivery guarantees
State Dependencies	Shared in-memory caches, session state, thread-local data	Runtime analysis, profiling	Requires externalized state management (Redis, etc.)
Timing Dependencies	Assumed ordering of operations, synchronous expectations	Transaction analysis, integration tests	Requires explicit coordination or saga patterns
Contract Dependencies	Implicit API contracts, assumed data formats, version expectations	Interface documentation, consumer analysis	Requires explicit versioning and contract testing

Dependency Graph Construction:

Visualizing dependencies as a directed graph reveals critical patterns:

DependencyGraph.ts
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;
  }
}

Runtime vs Static Analysis

Complexity Scoring

Not all services are equally difficult to extract. A rigorous complexity scoring system quantifies extraction difficulty, enabling informed prioritization decisions and accurate effort estimation.

Multi-Dimensional Complexity Assessment:

Complexity Scoring Dimensions
Dimension	Low (1-3)	Medium (4-6)	High (7-10)
Code Coupling	Isolated module with clear interfaces	Some shared utilities, moderate coupling	Deep entanglement with multiple modules
Data Coupling	Own tables, no foreign keys to other domains	Some shared lookup tables	Transactions span multiple domains
Team Complexity	Single team owns entirely	2-3 teams contribute occasionally	Shared ownership across 4+ teams
Business Logic Complexity	Simple CRUD operations	Moderate business rules	Complex workflows, state machines
External Integrations	No external systems	1-2 external APIs or services	Multiple external dependencies
Performance Criticality	Background processing, tolerant of latency	User-facing, moderate SLAs	Real-time, strict latency requirements
Data Volume	< 1GB, < 10K transactions/day	1-100GB, 10K-1M transactions/day	100GB, > 1M transactions/day
Test Coverage	80% coverage, comprehensive integration tests	50-80% coverage, basic integration tests	< 50% coverage, minimal testing

ComplexityScoring.ts
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';
}

Calibration Through Experience

Business Value Assessment

Value Dimensions to Consider:

Business Value Categories

•Development Velocity Impact: How much faster could the team ship features if this component were independent? Measure by release frequency and lead time.
•Scalability Requirements: Does this component need to scale independently? Components with traffic 10x higher than the rest of the system are strong candidates.
•Technology Modernization: Does extraction enable migration from legacy technology (outdated frameworks, unsupported languages) to modern stacks?
•Team Autonomy: Will extraction allow a team to work independently without coordinating deployments with other teams?
•Reliability Improvement: Is this component a frequent source of incidents? Would isolation prevent cascading failures?
•Cost Optimization: Can independent scaling reduce infrastructure costs? Components that over-provision for peak loads benefit from isolation.
•Strategic Enablement: Does extraction enable new business capabilities (B2B APIs, partner integrations, new product lines)?

BusinessValueAssessment.ts
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.',
    },
  ];
}

Quantify When Possible

Organizational Readiness Assessment

Readiness Dimensions:

Organizational Readiness Assessment Matrix
Dimension	Questions to Answer	Green Flags	Red Flags
Distributed Systems Skills	Does the team understand eventual consistency, network partitions, and distributed debugging?	Team has built/operated distributed systems before; training programs in place	Team only knows monolithic patterns; no distributed systems experience
DevOps Maturity	Can teams independently build, test, deploy, and monitor services?	CI/CD pipelines, infrastructure-as-code, observability stack in place	Manual deployments, shared environments, insufficient monitoring
Operational Capabilities	Who will operate services at 3 AM? Is there on-call structure?	Team-based on-call, runbooks, incident response processes defined	Central ops team handles everything; no per-team ownership
Cultural Alignment	Do teams embrace ownership? Are they willing to learn new approaches?	Strong ownership culture, growth mindset, experimentation encouraged	Blame culture, change-averse, 'not my job' mentality
Executive Support	Is leadership committed to the multi-year journey?	Clear budget commitment, migration metrics in OKRs, visible sponsorship	Migration competes with features; sponsor unclear; funding uncertain
Platform Capabilities	Does platform support service independence (container orchestration, service mesh, observability)?	Kubernetes, service mesh, centralized logging/tracing operational	Manual VM provisioning, no container support, limited observability

Common Organizational Readiness Gaps

•Testing Gap: Teams accustomed to integration tests within monolith lack experience with contract testing, consumer-driven contracts, and distributed test strategies.
•Monitoring Gap: Monolith monitoring focuses on single-system metrics. Distributed tracing, cross-service correlation, and business transaction monitoring require new skills.
•Data Management Gap: Teams familiar with transactions within single databases need training on eventual consistency, saga patterns, and distributed data management.
•Ownership Gap: In monoliths, shared ownership is common. Microservices demand clear ownership—teams must own build, deploy, and operate.
•Communication Gap: Independent services require explicit communication (APIs, events). Teams must learn contract definition, versioning, and backward compatibility.

Address Readiness Before Extraction

Prioritization Frameworks

The WSJF (Weighted Shortest Job First) Approach:

PrioritizationFrameworks.ts
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']

Alternative Prioritization Strategies:

Strategic Prioritization Approaches

•Strangler Sequence: Start with edge services (APIs, UI backends), work inward toward core. Each extraction reduces monolith surface area while core remains stable.
•Pain-Driven: Extract the most problematic components first—those causing incidents, blocking releases, or frustrating teams. High risk but high impact.
•Skill-Building: Start with simple extractions to build team capability, then tackle complex components when skills are proven.
•Business-Aligned: Prioritize by product roadmap. Extract components that need features first, maintaining velocity on strategic initiatives.
•Dependency-Ordered: Use topological sort on dependency graph. Extract leaf nodes first, working toward core services that everything depends on.
•Team-Based: Assign each team a component to extract in parallel, maximizing throughput while matching domain expertise.

Combine Approaches

Documenting and Communicating Assessment

Key Documentation Artifacts:

Assessment Documentation Suite

•Service Inventory Catalog: Living document listing all service candidates with ownership, complexity scores, value scores, and current status. Update as assessment evolves.
•Dependency Map Visualization: Graph visualization showing service interdependencies. Both high-level (service-to-service) and detailed (specific integration points) views.
•Migration Readiness Report: Summary of organizational readiness with identified gaps, remediation plans, and timeline for addressing prerequisites.
•Prioritized Migration Roadmap: Sequenced list of extraction targets with estimated effort, dependencies, team assignments, and expected value delivery.
•Risk Register: Enumeration of identified risks with likelihood, impact, mitigation strategies, and owners. Updated throughout migration.
•Decision Log: Record of key decisions made during assessment, including alternatives considered and rationale for choices. Invaluable for future teams.
•Business Case Summary: Executive-friendly document summarizing investment required, value to be delivered, timeline, and success metrics.

MigrationAssessmentSummary.md
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

Assessment Complete

1 / 5