Migration Architecture Patterns

Org Migration Architecture Patterns

The architecture-level decisions for org migration. Three shapes — merge, split, coexistence — each with its own discipline of metadata audit, data partitioning, identity continuity, and rollback planning. The cutover mechanics (freeze windows, parallel-run vs hard-cutover, runbook ordering) live in devops/go-live-cutover-planning. The upstream "should we have one org or many" decision lives in architect/multi-org-strategy. This skill is the how-to-execute layer in between.

What this skill is NOT. Picking go-live time-of-day, comm plans, and rollback runbooks is operations — that's the cutover skill. Whether multi-org is the right end-state at all is strategic — that's the multi-org-strategy skill. Here we assume the strategic call has been made and the cutover-runbook team is downstream.

Before Starting

• Name the direction explicitly. Merge (N → 1), split (1 → N), or coexistence (1 → 1+1 with a runtime bridge). Each has different failure modes; mixing them in a single design produces ambiguous ownership.
• Name the driver. Regulatory isolation (compliance), M&A consolidation, divestiture (split for sale), capacity / limits relief (split because hitting org-level governors), business-unit autonomy. The driver decides which trade-offs are acceptable — e.g. for divestiture, "no cross-org access ever again" outranks data continuity.
• Inventory before designing. Metadata audit (objects, fields, picklists, validation rules, automation) and data inventory (record counts, object relationships) both happen before the architecture decision is finalized. Designing without inventory produces a plan that hits unexpected metadata conflicts in week 2 of execution.
• Identify external dependencies on record IDs. Any external system that stores a 15- or 18-character Salesforce record ID will break on merge / split unless you plan a remapping layer. This is one of the highest-risk surprises.

Core Concepts

The three migration shapes

A real migration is often temporal coexistence followed by hard cutover — coexistence as a transition shape, ending in a merge or a clean split. Designing coexistence as a permanent state is rarer (and usually a sign that the multi-org-strategy decision wasn't actually made).

Pre-migration metadata audit (the most-skipped step)

Before any data moves, build a metadata delta between source and target. This is the single most important deliverable — skipping it is the most common cause of cutover failures.

For each metadata type, compare:

• Objects + fields. Same API name? Same data type? Same picklist values? Same field-level security? Custom objects with the same name but different schemas are landmines.
• Picklists. Same values? Same labels? Globally-shared vs per-record-type? Inactive values that must / must not flow?
• Validation rules. Will rules in the target reject data from the source? (Yes, often.) Plan a controlled disable / re-enable around the data load.
• Automation. Process Builders, Flows, Apex triggers. Will duplicate / conflicting automation fire on imported records? Almost always yes — disable bulk-load-side automation during migration, re-enable after data validation.
• Record types + page layouts. Mappings between source-org record types and target-org record types must be explicit per object.
• Profiles / permission sets. User access in target may be narrower than source — users who could see records in their old org may not see them in the new one without permission updates.

The audit produces a delta document — for every metadata mismatch, a decision: align source, align target, or accept the mismatch with a documented mitigation.

Record ID remapping

Salesforce record IDs are org-scoped. A 15- or 18-character ID from the source org has no meaning in the target.

External systems that have stored Salesforce IDs (CRMs that link to SF records, data warehouses, analytics tools, integration mapping tables) will fail if you don't remap.

The remapping pattern:

1. Capture source-Id → external-key before migration. Every record that's about to move must have a stable external key (custom external-Id field, or a synthetic one generated for the migration).
2. Insert into target with the external-Id field populated. Salesforce assigns new IDs.
3. Build the target-Id ↔ external-key ↔ source-Id table. Persist it.
4. Update external systems. Replace stored source IDs with target IDs using the remapping table.
5. Maintain the remapping table for the life of any external system that might still reference source IDs. Some never get fully migrated.

The most common failure: external systems that nobody knew were storing Salesforce IDs. Surface them in the inventory step; post-cutover discovery is expensive.

Coexistence bridges

When both orgs run simultaneously (transitional or permanent), choose the bridge based on what crosses the boundary:

Coexistence design must address: identity continuity (SSO), data continuity (which records are visible to which org), and rollback (can we cleanly disable the bridge if migration is paused or reversed?).

Common Patterns

Pattern A — Org merge with phased cutover

When to use. Two source orgs need to consolidate into one target. Both source orgs continue operating during the transition.

Sequence.

1. Inventory + audit. Metadata delta between source A, source B, and target. Data inventory. External integration inventory.
2. Target-org schema reconciliation. Resolve metadata deltas in target — pick winning picklist values, harmonize validation rules, resolve API name conflicts.
3. Build coexistence bridge. SSO so users from both source orgs can authenticate to target during cutover. Salesforce Connect or Platform Events for cross-org read during phased data load.
4. Pilot data load (≤1% of records). Validate the migration ETL produces correct records in target. Verify external-Id remapping table.
5. Wave 1 — least-coupled records first. Reference data, then customers, then transactions. Each wave validated before next.
6. External integration cutover. Update each external system's Salesforce-Id references using the remapping table.
7. Source-org freeze. Source orgs go read-only. Final delta sync from source to target.
8. Hard cutover. Source orgs decommissioned (or kept as archives). Target is canonical.

Each wave has a documented rollback: the previous wave's data state is recoverable.

Pattern B — Org split with regulatory isolation

When to use. A regulator demands that a subset of users / data be in a separately-governed org. (HIPAA-segregated patient data, geographic data residency, divestiture of a business unit.)

Critical constraint. After cutover, the new org must be operationally independent — no shared admin users, no shared integration credentials, no Salesforce Connect bridge into the regulated data.

Sequence.

1. Define the regulatory boundary. Which objects, which records, which users. The boundary is the most contested part of the design — get regulator sign-off.
2. Provision the new org. Edition, license counts, region (Hyperforce locality may be the regulatory driver).
3. Replicate the relevant metadata. Subset of source-org metadata, deployed to the new org. New org's metadata then evolves independently.
4. Move the records. Bulk insert with external-Id preservation; capture Id-remapping for any external integrations.
5. Cut over identity. Move users to the new org's IdP. Source-org access for migrated users is revoked at the same time.
6. Cut over external integrations. Each integration that referenced moved records now points at the new org.
7. Source-org cleanup. The migrated records / users are removed from source; source-org metadata is purged of fields that are now exclusive to the new org.

The most common failure: leaving a Salesforce Connect bridge in place "for convenience" — it defeats the regulatory isolation that was the entire point.

Pattern C — Coexistence as a permanent state

When to use. Two business units that share customers but operate distinct domains, with no executive mandate to consolidate. (Or a partnership where each side keeps its own org.)

Design.

• Identity. SSO via a shared IdP. Per-user permission set per org.
• Customer record. Master in one org, replica in the other via Platform Events. Updates flow both directions through a conflict-resolution rule (last-write-wins, or org-A-wins for some fields, org-B-wins for others).
• Lookup-only data. Salesforce Connect external objects on the consuming side; data lives in the producing org.
• Reporting. Either CRM Analytics with a cross-org connector, or a downstream warehouse that ingests from both.

Coexistence is harder to maintain than people expect. Schema drift between the two orgs is constant; the bridge needs ongoing investment.

Decision Guidance

Recommended Workflow

1. Confirm direction (merge / split / coexistence) and driver. Both must be named in writing before any other work.
2. Inventory metadata, data, and external dependencies in scope. Output: three documents — metadata delta map, data volume per object, external-system reference list.
3. Reconcile metadata in target. Resolve every delta from step 2.
4. Design the bridge / cutover / split mechanics. Pattern A / B / C from above as the starting template.
5. Plan record-Id remapping. Define external-Id strategy; capture source-Id → target-Id mapping.
6. Plan rollback per phase. Each cutover wave has a documented rollback that lands the system in a known good state.
7. Hand off to the cutover-runbook team. Ops sequencing, freeze windows, comm plan are downstream.

Review Checklist

• Direction (merge / split / coexistence) is named explicitly in the design.
• Driver (regulatory / M&A / limits / autonomy) is named.
• Pre-migration metadata audit document exists; every delta has a decision.
• Data volume inventory per object is captured.
• External-system inventory of Salesforce-Id references is complete.
• Record-Id remapping table design is documented.
• If split: regulatory isolation is enforced (no Salesforce Connect bridge into protected data).
• If coexistence: identity (SSO), data (sync mechanism), and rollback are each addressed.
• Per-phase rollback is documented.
• Hand-off to cutover team is explicit (where this skill ends).

Salesforce-Specific Gotchas

1. Skipping the pre-migration metadata audit is the #1 failure mode. Don't move data before reconciling object / field / picklist / validation / automation deltas. (See references/gotchas.md § 1.)
2. Salesforce record IDs are org-scoped. Any external system that stored an Id from the source org will break on merge / split unless remapped. (See references/gotchas.md § 2.)
3. Validation rules in the target will reject imported source data. Plan a controlled disable / re-enable around the data load. (See references/gotchas.md § 3.)
4. Automation in the target fires on imported records by default. Bulk migration without disabling automation produces side effects (auto-emails sent, fields auto-stamped) on data that didn't go through the normal lifecycle. (See references/gotchas.md § 4.)
5. Coexistence bridges are operational debt that grows over time. Schema drift is constant; budget for ongoing bridge maintenance, not just initial build. (See references/gotchas.md § 5.)
6. Splits "for regulatory isolation" with a Salesforce Connect bridge defeat the isolation. Hard rule: regulated splits have NO runtime bridge to protected data. (See references/gotchas.md § 6.)
7. Hyperforce region constraints affect data residency during merge / split when source and target are in different regions. (See references/gotchas.md § 7.)

Output Artifacts

Related Skills

• architect/multi-org-strategy — the upstream "single-org vs multi-org" decision; consult before this skill if the strategic call hasn't been made.
• devops/go-live-cutover-planning — the downstream operational cutover (freeze windows, comm plan, parallel-run vs hard-cutover); consult after this skill.
• data/bulk-migration-runbook — Bulk API patterns, parent-child sequencing, error-row handling for the actual data load.
• architect/hybrid-integration-architecture — when the bridge crosses into AWS / Heroku / MuleSoft territory.
• security/byok-key-rotation — when migrated data is Shield-encrypted and key custody must move with the data.