Branch by Abstraction: The Safe Way to Replace a Module in Production

In this article:

• The Problem Branch by Abstraction Solves
• The Four Phases of Branch by Abstraction
• Parallel Run: Verifying the New Implementation
• When to Use Branch by Abstraction vs. Strangler Fig
• Conclusion

Branch by abstraction is a technique for replacing a component in a running system without feature branches, without big-bang releases, and without downtime. The idea is simple: introduce an abstraction layer that sits between the callers and the component you want to replace, then build the new implementation behind that abstraction, gradually switch over, and remove the old implementation once the migration is complete.

This approach lets teams replace a module in production incrementally, shipping to production throughout the migration rather than after it. The ability to roll back at any point, down to a single feature flag toggle, is what makes it suitable for production systems where availability is not negotiable.

---

The Problem Branch by Abstraction Solves

The traditional approach to replacing a module is: create a branch, rewrite the module, merge, test, deploy. This has three problems.

First, long-lived branches diverge. A two-week branch in an active codebase accumulates conflicts. A two-month branch becomes a merge event that consumes an engineering week and introduces subtle bugs that were not in either the original or the new code, only in the merge.

Second, big-bang releases concentrate risk. All the risk of the migration is realized at the moment of deployment. If something is wrong, you find out in production, not during incremental validation.

Third, parallel development stops. While the rewrite branch exists, the team cannot ship features to the area being rewritten without duplicating effort across two versions.

Branch by abstraction eliminates all three problems. There is no long-lived branch: the new implementation is built on the main branch behind a flag. There is no big-bang release: traffic switches gradually. There is no parallel development freeze: the abstraction layer means both old and new implementations coexist and can be improved independently.

---

The Four Phases of Branch by Abstraction

Phase 1: Introduce the abstraction. Create an interface or abstract class that captures the contract of the module you want to replace. Update all callers to use the abstraction rather than the concrete implementation. The existing implementation becomes the first concrete implementation of the new abstraction.

At this point, nothing has changed functionally. All callers still reach the same code through the new abstraction layer. This phase should be a standalone PR that is easy to review and deploy.

Phase 2: Build the new implementation. Create a second concrete implementation of the abstraction. This is the new code you are migrating to. Build it behind the abstraction so it can be developed and tested independently. The old implementation is still in production; the new one is not yet called by any production traffic.

Phase 3: Switch traffic incrementally. Introduce a feature flag that controls which implementation the abstraction routes to. Start with 0% of traffic to the new implementation, then increase: 1%, 5%, 10%, 25%, 50%, 100%. At each step, monitor error rates, latency, and business metrics. If anything degrades, flip the flag back. The rollback cost is near zero.

During the switchover, consider running the parallel run pattern: call both implementations, compare the outputs, log discrepancies but return only the old implementation’s result. This gives you visibility into behavioral differences before any user-facing impact.

Phase 4: Remove the old implementation. Once 100% of traffic is on the new implementation and it has been stable for an agreed period, remove the old implementation and the feature flag. The abstraction layer may or may not be worth keeping depending on whether it provides ongoing architectural value.

---

Parallel Run: Verifying the New Implementation

The parallel run pattern is a verification technique often used alongside branch by abstraction. Both the old and new implementations are called with the same inputs. The outputs are compared. Discrepancies are logged.

This is particularly valuable when the old implementation has undocumented behavior or edge cases that are not covered by tests. Running both in parallel through production traffic reveals divergences that no test suite would catch.

Implementation: wrap both calls in the abstraction layer. Call old, call new, compare outputs. If they match, log “consistent.” If they differ, log the inputs and both outputs. Return the old implementation’s result to the caller regardless, so no user is affected by the comparison.

After running parallel for a sufficient period (often one to two weeks of normal production traffic), review the discrepancy log. Some discrepancies will be bugs in the new implementation. Some will be undocumented behaviors in the old one that you need to either replicate or consciously change. This log is the most valuable artifact in the migration: it tells you exactly where the two implementations differ before you commit to the new one.

---

When to Use Branch by Abstraction vs. Strangler Fig

Branch by abstraction operates within a single codebase, replacing one component with another within the same deployable unit. Use it when you are replacing a class, a module, a library, or an internal service.

The strangler fig pattern operates at the system level, gradually routing requests from an old system to a new one using a proxy or gateway layer. Use it when you are migrating from one application to another, from a monolith to microservices, or from one external API to a replacement.

The two patterns share the same underlying principle: incremental switchover with the ability to roll back, running old and new in parallel during verification. They differ in scope and in where the abstraction lives.

For large-scale legacy modernization that involves both internal refactoring and service decomposition, both patterns are often used simultaneously at different levels of the architecture. Read more about the full approach in the legacy modernization guide.

---

Conclusion

Branch by abstraction is the correct approach when a module needs to be replaced in a production system and downtime or long-lived branches are not acceptable. It requires more upfront investment than a direct rewrite, but it eliminates the highest-risk moment of any migration: the big-bang deployment.

Teams that apply this technique consistently replace components that would otherwise take six-month rewrites in six-week incremental migrations, with zero downtime and full rollback capability at every step.

Does your codebase have these problems? Let’s talk about your system