Evolving Architecture Without Breaking Production

The second-system effect is reliable: a ground-up rewrite of a working system takes three times as long as estimated and ships with bugs the original had already fixed years ago. The production knowledge problem is real and underestimated. The original system contains years of accumulated edge-case handling: timezone bugs, malformed input tolerance, specific retry behaviors for downstream dependencies: most of it undocumented and discoverable only under production load.

All-at-once cutover compounds the risk. The new system has never seen production traffic at scale. If it fails on day one, rollback is painful: data written to the new system's schema may not be compatible with the old system, and any migration that ran during cutover must be reversed. Teams that committed to "we can't go back" cutover dates have lost weekends and user trust over exactly this scenario.

The right model is architecture evolution, not replacement. The goal is to migrate incrementally, run old and new systems in parallel, and cut over gradually with the ability to reverse any individual migration step. Every mechanism in this module exists to make incremental migration safe and observable.

One useful heuristic: if your migration plan has no rollback steps, it is not a migration plan: it is a bet.

Key Takeaways

• →Big-bang rewrites routinely take 3x longer than estimated and rediscover bugs the original had already fixed
• →Production knowledge lives in the code, not in documentation: incremental migration transfers it implicitly
• →A migration plan with no rollback steps is a bet, not a plan