liveBook · Manning

Migration

As explained in Fast by Default

An architectural migration is a planned transition from an existing software architecture to a replacement architecture, often while both systems temporarily coexist.

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

How Fast by Default covers it

How deep it goes
Explains coexistence costs, phased execution, success criteria, and decision points, but does not detail system-specific implementation.
Examples
Uses page-load reduction, origin-traffic reduction, and a four-phase strangler fig migration as planning examples.
What it assumes
Assumes an existing architecture and defined performance goals, while treating migration phases and coexistence planning as explicit work.
What you can do after
Evaluate migration progress through targets, phased success criteria, coexistence costs, and explicit continue-or-stop decisions.
How it connects
Connects architectural migration with performance targets, caching, backend-for-frontend, data synchronization, routing, and strangler fig migration.

Also explained in

Compare how 23 books explain migration →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Fast by Default. The section links point to the parts of the book it draws on.