An architectural migration is a planned transition from an existing architecture to a replacement architecture, often while both systems temporarily coexist. Define measurable targets first: the target determines whether the new architecture succeeds and when the migration can stop. section 5.5.2
Plan the migration as an operational program:
- Account for coexistence costs, including maintaining two systems, synchronizing data, and routing requests. section 5.5.2
- Use explicit phases: establish the pattern in a low-risk area, prove it with additional migrations, scale it, then decommission the legacy system. section 5.5.2
- Attach success criteria and decision points to every phase so the team can continue, adjust, or abandon the migration honestly. section 5.5.2
Table 5.3 Discovering when incremental fixes stop working
|
Symptom
|
Typical fix
|
Fails when
|
Rearchitect if
|
|
Slow page loads
|
Add caching
|
Cache hit rates plateau; personalized content uncacheable
|
Still slow after caching everything possible
|
|
API latency
|
Optimize queries, add indexes
|
Queries are already optimized; latency is caused by network hops
|
The database is fast, but requests are still slow
|
|
Deployment bottlenecks
|
Better CI/CD, feature flags
|
Deployments are fast, but changes still break unrelated features
|
Fast deploys, slow safe changes
|
|
Scaling limits
|
Vertical scaling, read replicas
|
Single-write bottleneck; data too large for one machine
|
Maxed out the largest instance
|
|
Test failures cascade
|
Better test isolation
|
Tests isolated, but code changes still ripple
|
Tests pass in isolation, yet fail together
|
Use the failure-pattern table to identify when incremental fixes have reached their limit and rearchitecture is justified. section 5.5.2






















