+------------------------------------------+
|                Facade                     |
+---------------+---------------+----------+
                |               |
    +-----------v----+   +------v------+
    |   Legacy       |   |    New      |
    |   System       |   |   System    |
    +----------------+   +-------------+

Phase 1: Facade routes everything to legacy
Phase 2: Migrate feature by feature to new
Phase 3: Eventually remove legacy entirely

Step 1: Create abstraction layer
Step 2: Implement old behavior behind abstraction
Step 3: Create new implementation
Step 4: Switch to new implementation
Step 5: Remove old implementation

Request --+-- Legacy System ---+
          |                    +-- Compare -- Log differences
          +-- New System ------+

// Step 1: Dual-write to both databases
async function saveUser(user: User): Promise<void> {
  await legacyDb.saveUser(user);
  await newDb.saveUser(transformUser(user));
}

// Step 2: Read from new, fallback to legacy
async function getUser(id: string): Promise<User> {
  try {
    return await newDb.getUser(id);
  } catch {
    return await legacyDb.getUser(id);
  }
}

// Step 3: Read from new only
// Step 4: Write to new only
// Step 5: Decommission legacy

// Version coexistence
app.get('/api/v1/users/:id', legacyGetUser);
app.get('/api/v2/users/:id', newGetUser);

// Feature flag migration
app.get('/api/users/:id', async (req, res) => {
  if (await featureFlag('new_user_api')) {
    return newGetUser(req, res);
  }
  return legacyGetUser(req, res);
});

// Before: Callback-based
function getUser(id: string, callback: (err: Error, user: User) => void) {
  db.query('SELECT * FROM users WHERE id = ?', [id], callback);
}

// After: Promise-based (wrapper first)
function getUserAsync(id: string): Promise<User> {
  return new Promise((resolve, reject) => {
    getUser(id, (err, user) => {
      if (err) reject(err);
      else resolve(user);
    });
  });
}

// After: Modern implementation
async function getUser(id: string): Promise<User> {
  return db.query('SELECT * FROM users WHERE id = $1', [id]);
}

describe('Legacy UserService', () => {
  it('should return user with computed display name', () => {
    // Capture what the legacy code actually does
    const result = legacyUserService.getUser('123');

    // Record the actual behavior (even if unexpected)
    expect(result.displayName).toBe('John D.');
    expect(result.lastLogin).toBeInstanceOf(Date);
    // Note: Discovered that lastLogin is always UTC
  });
});

// Record outputs from legacy system
const goldenMaster = await recordLegacyOutputs(testInputs);
saveToFile('golden-master.json', goldenMaster);

// Compare new system against golden master
test('new system matches legacy behavior', async () => {
  const newOutputs = await runNewSystem(testInputs);
  expect(newOutputs).toEqual(goldenMaster);
});

# Feature flag for instant rollback
flags:
  new_payment_system:
    enabled: true
    rollout: 10%  # Start with 10% of traffic

# If issues detected:
# - Set enabled: false
# - Or reduce rollout: 0%

## Migration Plan: [System/Component]

### Current State
- **Technology**: [Current tech stack]
- **Pain Points**: [Why migrating]
- **Dependencies**: [What depends on this]

### Target State
- **Technology**: [New tech stack]
- **Benefits**: [Expected improvements]

### Migration Strategy
[Chosen approach and why]

### Phases

#### Phase 1: Preparation
- [ ] Document current behavior
- [ ] Add characterization tests
- [ ] Create abstraction layer

#### Phase 2: Migration
- [ ] Implement new component
- [ ] Dual-write/parallel run
- [ ] Gradual traffic shift

#### Phase 3: Cleanup
- [ ] Remove legacy code
- [ ] Update documentation
- [ ] Decommission old systems

### Risk Assessment

| Risk | Probability | Impact | Mitigation |
|------|-------------|--------|------------|
| [Risk] | High/Med/Low | High/Med/Low | [Strategy] |

### Rollback Plan
[How to revert if needed]

### Success Metrics
- [ ] All tests passing
- [ ] Performance maintained/improved
- [ ] No data inconsistencies
- [ ] Zero downtime

### Timeline
- Phase 1: [dates]
- Phase 2: [dates]
- Phase 3: [dates]