Implementing Migration Patterns

1. Strangler Fig Pattern

Step	Detail
Façade	Routing layer in front of legacy
Extract	Move one capability at a time to new service
Route	Façade routes that capability to new service
Repeat	Until legacy is empty
Decommission	Remove legacy when traffic = 0

Client ─▶ Façade ─┬─▶ Legacy (shrinking)
                  └─▶ NewSvcA, NewSvcB, ... (growing)

Aspect	Detail
Purpose	Translation layer between new service domain and legacy model
Benefit	New service stays clean; legacy quirks isolated
Implementation	Adapter / façade with mapping logic

Step	Detail
1. Abstract	Introduce interface over existing implementation
2. Migrate Callers	All callers go through abstraction
3. Add New Impl	Implement new behavior behind same abstraction
4. Switch	Toggle to new impl gradually
5. Remove Old	Delete old impl when stable

Aspect	Detail
Mechanism	Run old + new; compare outputs; alert on diffs
Source of Truth	Old, until confidence achieved
Tools	GitHub Scientist, custom diff loggers

Aspect	Detail
Mechanism	Toggle controls old vs new path; per-tenant or %
Benefit	Instant rollback; gradual rollout
Cleanup	Remove toggle after full migration

Principle	Detail
Small Steps	Many small migrations vs one big-bang
Always Releasable	System works after every step
Reversible	Each step rollback-able
Measured	Migration progress tracked (e.g., % moved)

Aspect	Detail
Mechanism	Write to both old + new stores during migration
Risks	Inconsistency on partial failure
Better Alternative	CDC from old → new (single source of write)
Verification	Reconciliation jobs compare both stores

Warning: Dual write is dangerous — without 2PC, partial failures cause divergence. Prefer CDC or transactional outbox.

Aspect	Detail
Purpose	Simplified interface over complex legacy
Use	New clients integrate with façade, not legacy directly
Benefit	Decouples consumers from migration churn

Aspect	Detail
Mechanism	Wrap legacy as a "service" with REST/gRPC API
Benefit	Treat legacy as a microservice; defer rewrite
Watch For	Wrapping ≠ refactoring; tech debt remains

Step (Expand & Contract)	Detail
1. Expand	Add new column / table; keep old
2. Backfill	Migrate data old → new
3. Dual Write	App writes both; reads still old
4. Switch Reads	Read from new; verify
5. Stop Old Writes	App writes new only
6. Contract	Drop old column / table
Tools	Flyway, Liquibase, gh-ost (online)