Branch by Abstraction

Definition

Branch by Abstraction is a migration technique for replacing a deeply embedded component that cannot be intercepted at an external seam. Rather than using a proxy (as in Strangler Fig), an abstraction layer is created inside the codebase, allowing the old and new implementations to coexist until the new one is proven and the old can be removed. (→ Monolith To Microservices)

The technique works where the strangler fig does not: when the capability to be migrated is not called from outside the monolith but from many places within it.

The Five Steps

1. Create an abstraction — introduce an interface or abstract class that defines the capability being migrated. All callers within the monolith are updated to call through this abstraction rather than directly into the existing implementation.

2. Use the abstraction — once all callers use the abstraction, the existing implementation sits behind it. At this point the codebase compiles and behaves exactly as before — the abstraction is a pure refactor.

3. New implementation — build the new implementation (typically a new service) alongside the existing one. The abstraction now has two concrete implementations: the old one and the new one.

4. Switch — update the abstraction to route calls to the new implementation. This is where traffic is redirected. The switch can be controlled by a feature toggle so it can be flipped at runtime without a deployment. Both implementations remain in place during this phase.

5. Clean up — once the new implementation is stable and proven, remove the old implementation and delete the feature toggle.

Feature Toggles

A feature toggle (feature flag) allows the switch in step 4 to be applied gradually and safely:

• Start with 1% of traffic; ramp up as confidence grows
• Roll back instantly by flipping the toggle without a code change or deployment
• Use per-cohort toggles (e.g., internal users first, beta users second) to control blast radius

Feature toggles during migration are temporary infrastructure — remove them as part of the clean-up step. Accumulated feature toggles become a maintenance burden. See Feature Flags for Hodgson's toggle taxonomy and lifecycle discipline (the migration-toggle case is a "release toggle" with a short expected lifetime).

Verify Variant (Steve Smith)

The verify variant approach is an extension for high-risk switches (→ Monolith To Microservices): both implementations run simultaneously for the same request; their outputs are compared; mismatches are logged for investigation.

Key behaviour: the system always returns the old implementation's result to the caller while the new implementation runs in parallel. If they agree, the result is the same. If they disagree, the mismatch is logged but the old result is still returned — the system does not fail.

This is automatic fallback by construction: even if the new implementation crashes or returns wrong results, the user experience is unaffected. Confidence grows as the mismatch rate approaches zero.

The verify variant is related to the Parallel Run pattern but operates at the in-process abstraction layer rather than at the service call boundary.

When to Use

• The capability is deeply embedded inside the monolith with many internal callers and no clean external boundary
• A Strangler Fig proxy cannot be applied because the entry point is internal, not at an HTTP or message boundary
• The team wants to keep the migration as a series of safe, reversible steps inside the existing codebase before introducing service infrastructure

When to Prefer Strangler Fig Instead

• There is a clean external seam (HTTP endpoint, message queue, FTP boundary) where traffic can be intercepted without touching the monolith's internals
• The monolith cannot be safely modified to introduce an abstraction without high risk

Relationship to Parallel Run

Branch by Abstraction provides the mechanism (the abstraction layer and the two implementations); Parallel Run provides the verification strategy (running both and comparing results). They are frequently combined: use branch by abstraction to create the coexistence structure, and the verify variant / parallel run approach to build confidence before completing the switch.

Related Patterns

• Strangler Fig — the alternative for extracting capabilities at an external seam; simpler when applicable
• Parallel Run — running both implementations simultaneously to verify the new one before committing
• Progressive Delivery — broader pattern family covering the staged-rollout mechanics
• Feature Flags — release toggles as the migration switch's runtime control
• Evolutionary Architecture — branch by abstraction as an enabling technique for incremental, safe architectural change
• Microservices Architecture — the target state after the migration is complete
• Migration Pattern Selection — decision guide for when to choose branch by abstraction vs other migration patterns