Migrating a Live Platform Without Downtime: Compatibility Layers, Shadowing and Traffic Pinning
How to replace a system that cannot go down: keep old contracts alive, mirror traffic to compare answers, pin each trip to one system, and roll back by region.
On this page
Big-bang cutovers fail in the same way every time: everything works in testing, something nobody modelled happens in production, and rollback is a plan nobody ever practised. The alternative is a migration that is boring by design, with the new system earning traffic in small, reversible steps.
The situation
A fulfillment platform sat at the centre of everything: over two million transactions per second, a million-plus concurrent users, billions of database transactions a day, and hundreds of services depending on it as the source of truth for trip state. It was organised as city-level pods with shared-nothing demand and supply services, backed by a distributed key-value store and cache, kept consistent with the saga pattern.
That design favoured availability and had known costs: eventual consistency that needed reconciliation, multi-entity writes done through RPC that required constant state verification, and a vertical ceiling on how big a pod could be for the busiest cities. The redesign merged demand and supply into one application layer over a cloud database, moving consistency into the data layer. The hard part was getting there.
Technique 1: a backward compatibility layer
Put a bridge in front of the new system that honours the old API contracts and event schemas.
Give the layer an expiry date and a metric: which consumers still use which old endpoints, so you know when it can be deleted.
Technique 2: shadow validation
Every request sent to the old system is mirrored to the new one. Responses are compared key by key, and differences go into an observability system.
client --> old system --> response A (returned to user)
\--> new system --> response B (compared, never returned)
diff(A, B) -> log, classify, alert
Comparison is not binary. You define tolerances for known benign differences, such as ordering, timing or transient state. Then triage:
| Difference | Response |
|---|---|
| Inside a pre-approved tolerance | Log for analysis, no action |
| Edge-case timing mismatch | Log, review in batch |
| Affects user function or a critical data rule | Prioritise immediately, fix before rollout |
This approach was popularised for refactoring by tools that run old and new code side by side and report mismatches. It catches the bugs that test suites never imagined, because the test inputs are real.
Mirrored requests must not cause side effects: no duplicate charges, no duplicate notifications. Run shadow traffic against write-isolated paths or stub the effects, and verify that the shadow system cannot slow the primary one.
Technique 3: pre-rollout work
- End-to-end tests
Complete journeys across all integrations, to catch interface problems between components.
- Load tests at or beyond peak
Confirm latency and stability under realistic and surge traffic before any user hits it.
- Database warm-up
Generate synthetic load to fill caches and split partitions, so the first real traffic does not meet a cold, unsplit datastore. Cold starts in autoscaling databases are a classic first-hour outage.
Technique 4: traffic pinning
A trip involves many interactions over its life: driver updates, route changes, fare calculation. If half of them hit the old system and half the new, the state fragments. Pinning keeps every interaction for an entity on the system where it began.
- Record which system owns each in-flight entity (or the rider and driver identifiers involved).
- Route all later requests for that entity back to its owner until it completes.
- Start with idle or low-risk users, then move new entities, then wider cohorts, city by city.
Entities that finish on the old system simply drain away, and the old system empties without ever needing a mid-flight state transfer. This avoids the hardest problem in migration, which is moving live state.
Technique 5: observe at fine grain, roll back at region grain
Aggregate metrics should stay flat as traffic drains from one system and fills the other. Flat averages hide local failures, so measure at city or tenant level: transaction success rate, latency, error rate, completion rate, driver availability.
- Dashboards show both systems side by side, so you watch one fill as the other drains.
- Alerts target the local regression: completion rate drops in one city.
- Rollback is a routing change for that region, not a redeploy. Rehearse it, time it, and make sure the old system is still sized to take the traffic back.
What it costs
| Cost | Why |
|---|---|
| Two systems in production for a long time | Infrastructure spend and the on-call load of running both |
| Observability complexity | Comparing, correlating and alerting across systems |
| Compatibility layer upkeep | Both contracts must stay aligned until the old one retires |
| Slower to finish | Phases, soak periods and approvals trade speed for safety |
That cost is the price of never having a bad day.
Do
Define success and rollback thresholds before the first percent moves, keep the old system fully capable until after the last cohort, and schedule the removal of every temporary component.
Don't
Declare victory when traffic reaches 100 percent. Decommission the old system and the compatibility layer, or the migration quietly becomes your permanent architecture.
Takeaway
A zero-downtime migration is an argument made with evidence: shadow comparison shows the new system gives the same answers, load tests show it can take the traffic, pinning shows state is never split, and per-region metrics with an instant rollback show any mistake is small and reversible. Do all of that, and cutover is the least dramatic day of the project.
Frequently asked questions
What is shadow validation?
Mirroring real requests to the new system while the old one still serves users, then comparing the two responses field by field. Differences are logged and classified. It tests the replacement against real traffic and real data shapes without any user ever seeing the new system's answers.
What is traffic pinning?
Routing every operation on a stateful entity, such as a trip or an order, to the one system that created it for its whole lifetime. New entities start on the new system while in-flight ones finish on the old, so no entity is ever split across two stores.
Why keep a backward compatibility layer during a migration?
So consumers of the old APIs and events do not have to change at the same time as the platform underneath. Each team can adopt the new interface on its own schedule. The price is extra complexity and latency, so plan its removal from the start.
How do you decide when to roll back?
Define, before starting, the metrics and thresholds that trigger rollback, such as completion rate, error rate and latency, measured per region or tenant. Make rollback a tested, automated switch of routing, and keep the old system fully running until the new one has proven itself.

/* Comments */
Comments are offline right now — we reconnect automatically, nothing is lost.