Incremental migration
Six phases with a rollback at every boundary
Keep the current system serving users until the replacement proves the same essential contract. Freeze only what is necessary and record every irreversible step.
Inventory the live contract
Keep stableCurrent production behavior, URLs and accounts
ReplaceAssumptions with an evidence-based system and ownership map
ProofCritical journeys, dependencies, data stores, vendors, domains and owners are recorded
Secure ownership and exports
Keep stableUser access and service continuity
ReplacePersonal accounts and undocumented provider-only state
ProofOrganization controls source, domain, data exports, billing and recovery
Create the target foundation
Keep stablePublic URLs, content model and essential product rules
ReplaceNon-portable build, configuration and deployment assumptions
ProofA clean environment builds, deploys and observes a representative thin slice
Move data and identity
Keep stableStable identifiers, permissions and user expectations
ReplaceProvider-specific storage or authentication only after parity tests
ProofCounts, relationships, role boundaries and recovery flows reconcile
Run parallel acceptance
Keep stableCurrent system as the authoritative fallback
ReplaceJourneys incrementally behind controlled routing or release scope
ProofCritical outcomes, accessibility, performance and failure behavior meet acceptance criteria
Cut over and retire
Keep stableMonitoring, support, redirects and recoverable archives
ReplaceTraffic, integrations and operational ownership
ProofDNS, redirects, events, email, jobs and alerts work under real traffic
Preserve the interfaces users depend on
The migration unit is a contract, not a file
Exported components can be useful, but users depend on URLs, identities, data relationships, messages, permissions and recovery behavior. Search engines depend on stable canonical URLs and redirects. Operations depend on secrets, schedules, webhooks and alerts that may never appear in the source export.
Write characterization tests around critical behavior before changing architecture. If the existing behavior is wrong, document the intended correction separately so migration parity does not silently become product redesign.
- Separate migration, redesign and feature work
- Verify exports before announcing a cutover
- Lower DNS TTL only as part of a documented plan
- Do not delete the old system until recovery and retention duties are resolved
Decision matrix
What commonly gets lost in a code-only migration
Use this as a discovery list, then remove items that demonstrably do not apply to the product.
| Surface | Often missed | Failure after cutover | Verification |
|---|---|---|---|
| URLs and SEO | Canonicals, redirects, metadata and sitemap behavior | Traffic lands on errors or duplicate pages | Crawl old and new URL sets and test redirect targets |
| Identity | Password reset, sessions, roles and external login settings | Users lose access or gain incorrect permissions | Role matrix and account recovery rehearsal |
| Data | Relationships, files, queues, timestamps and deleted states | Records are incomplete or inconsistent | Reconciliation queries and sampled journey checks |
| Integrations | Webhooks, allowlists, schedules and signing secrets | Payments, email or background work silently stop | Provider-by-provider event test |
| Operations | Logs, alerts, backups, support and billing ownership | The new system fails without diagnosis or recovery | Incident and restore exercise |
| Licenses | Fonts, images, packages and builder-specific components | Use is restricted or assets disappear | Asset and dependency inventory with terms |
Applied example
Migration failure: the homepage moved, the product did not
A team exports the generated frontend and deploys it independently. The old platform still owns authentication, scheduled jobs, file storage and webhook secrets, but the cutover plan treats the repository as complete.
- The visible pages load, creating false confidence.
- Account recovery and background workflows fail only after users act.
- The team cannot retire the old subscription because critical state remains there.
- A system inventory and thin-slice deployment would have exposed the incomplete boundary.
Plain answers
Migration questions
Should we rewrite the website during migration?+
Avoid combining the projects unless a requirement makes it necessary. Parity, redesign and new features create different failure modes and are easier to verify separately.
Can we migrate if the platform has no source export?+
Possibly, but treat it as rebuilding behavior and migrating data rather than moving code. Verify contractual rights and prioritize portable content, data, domains and user journeys.
When can the old system be deleted?+
After cutover stability, rollback expiry, data reconciliation, retention obligations, billing and recovery evidence are explicitly resolved—not immediately after the new homepage loads.