Skip to content

CONCEPT Cited by 1 source

Dual-architecture compatibility

Definition

Dual-architecture compatibility is the discipline of keeping a single codebase buildable and testable under both the old and new versions of an underlying runtime or renderer, for the duration of a migration window. It is the mobile-app analogue of blue/green at the framework layer — except "blue" and "green" are two builds of the same source tree, not two deployments of different code.

The canonical wiki instance is Shopify's 2025 migration of Shopify Mobile + Shopify POS to React Native's new architecture (see sources/2025-09-12-shopify-migrating-to-react-natives-new-architecture).

Why it's necessary for large mobile apps

Three forcing conditions, all present at Shopify's scale:

  1. Weekly release cadence — Shopify ships weekly to merchants throughout the migration. Feature work cannot pause for months while a framework swap happens.
  2. No remote feature-flag gate — the new architecture is a native binary property; it can't be toggled on/off in production by a remote config change. Rollback means shipping a new binary.
  3. Concurrent engineer count — hundreds of engineers writing new features in parallel. Without CI enforcement, someone will inadvertently introduce code that breaks the new-architecture build, and the breakage compounds over weeks.

Dual-architecture compatibility turns the migration from "keep the new arch green as engineers change things" (a continuous operations problem) into "PRs that break either architecture can't merge" (a gating problem). The latter is tractable.

Mechanism

Three components, all present in Shopify's approach:

  • Dual-architecture CI builds on every PR — see patterns/dual-architecture-ci-builds. Shopify used their internal TopHat platform (systems/tophat-shopify) to generate builds under both architectures on every PR; PRs can't merge unless both pass.
  • Feature-flagged dual implementation for third-party modules that don't yet support both architectures — see patterns/feature-flagged-dual-implementation. Conditional imports / forked code paths flagged in development mode on the new architecture.
  • Library-side dual-architecture support — library maintainers ship a single version that works on both architectures (example: FlashList v2 alpha). This eliminates the "which library version do I pin per architecture?" cross-product that conditional versioning creates.

Costs

  • Duplicated testing matrix. Every change is now tested under two architectures, doubling build time and CI compute.
  • Forked module code. Feature-flag forks are temporary tech debt; Shopify explicitly adds "deprecation warnings to temporary code paths for post-migration cleanup."
  • Slower cleanup. Removal of the old-architecture code path can't happen until after shipping, and the temporary code ages in the codebase for the duration of rollout plus recovery.

All three costs are accepted because the alternative — pausing feature development or running long-lived feature branches — is worse for a weekly-release app serving millions.

Last updated · 470 distilled / 1,213 read