Incremental Monolith Migration: A Safer Path to Modernization

Migrating a large legacy monolith often feels like an insurmountable task. The common approach, a "big-bang" rewrite, carries immense risk. It frames the migration as a single, all-encompassing event: move the application, the database, the users, then flip a switch. This creates a dangerous assumption that the old and new systems must exchange places simultaneously.

Such a strategy introduces an overwhelming number of variables changing at once – runtime, framework, database, APIs, authentication, data model, business logic, and external integrations. If the final cutover fails, identifying the root cause from countless possibilities (e.g., a pricing change, data loss, authentication mismatch, new runtime behavior, or a timeout) becomes a nightmare. Incremental migration offers a more controlled, less risky alternative by reducing the number of changing variables at each step, making changes smaller, observable, and reversible.

Shifting Focus: From Applications to Migration Slices

Instead of asking, "How do we migrate this monolith?", a more effective question is: "What's the smallest meaningful business capability we can move independently?" These are your "migration slices." Examples include Calculate Order Total, Generate Invoice, or Create Shipment.

A good migration slice should possess:

• Clear inputs and outputs
• Known side effects and understood dependencies
• Observable behavior
• A defined rollback path

This approach transforms a vague "replace the billing module" into a concrete, manageable unit like Generate Invoice, which takes an orderId and, through specific steps (load order, calculate taxes, generate invoice number), produces an invoice with specific side effects like storing the invoice or publishing an invoice.created event.

Choosing Your First Capability Wisely

The initial migration slice is crucial for validating your approach. It should be meaningful enough to provide real learning but not so critical that a failure leads to catastrophic consequences. Ideal first candidates often have:

• Moderate traffic
• Limited external dependencies
• Clear, well-understood behavior
• Good test coverage
• Few transactional boundaries
• Low "blast radius" if something goes wrong

Think of Generate Customer Statement as a better starting point than Authorize Payment. This first step validates your routing, deployment, observability, data access, testing, and team workflow before tackling higher-stakes capabilities.

Establishing Boundaries with the Strangler Fig Pattern

A fundamental step in incremental migration is creating a clear boundary between legacy and new code. If your legacy application has a function like:

typescript async function generateInvoice( orderId: string ) { // legacy implementation }

Introduce an interface to define the contract:

typescript interface InvoiceGenerator { generate( orderId: string ): Promise<Invoice>; }

Then, wrap your legacy logic in an implementation:

typescript class LegacyInvoiceGenerator implements InvoiceGenerator { async generate( orderId: string ): Promise<Invoice> { // existing behavior } }

Your new, migrated implementation will adhere to the same interface:

typescript class NewInvoiceGenerator implements InvoiceGenerator { async generate( orderId: string ): Promise<Invoice> { // migrated behavior } }

This technique, part of the Strangler Fig pattern, allows new behavior to gradually grow around and eventually replace the old system. The caller is decoupled from the specific implementation, enabling you to switch between LegacyInvoiceGenerator and NewInvoiceGenerator without modifying the calling code. Conceptually, incoming requests are routed, with the legacy path initially handling 100% of traffic, gradually shifting to the new path until the legacy path can be removed for that specific capability.

Coexistence, Explicit Routing, and Progressive Rollout

During an incremental migration, legacy and new implementations will run concurrently. The critical question is how requests are routed between them. Strategies include using feature flags, tenant IDs, user groups, request headers, regions, or percentage-based rollouts.

Crucially, routing must be explicit and observable. Avoid implicit fallbacks like a try-catch that silently defaults to the legacy service upon new service failure:

typescript try { return await newService.call(); } catch { return legacyService.call(); }

This can mask failures, preventing you from accurately assessing the health of your migration. Instead, make the routing decision first, record it, then execute the chosen implementation:

typescript const route = migrationPolicy.route(request); metrics.increment( invoice.route.${route} ); if (route === "migrated") { return migrated.generate( request.orderId ); } return legacy.generate( request.orderId );

This provides clear metrics on traffic distribution, latency, error rates, and business outcomes for both paths. Begin routing with low-risk traffic, such as internal users or test environments, before gradually increasing production traffic (e.g., 1%, then 5%, then 10%, up to 100%). Each increase should be data-driven, based on evidence of correct behavior.

Validating Behavior with Differential Testing

Differential testing is a powerful technique where you run both the legacy and migrated implementations with the same input and compare their observable behavior (return values, errors, state changes, side effects). Before live routing, this comparison helps detect discrepancies. During rollout, you can use "shadow traffic" – routing a real production request to the active implementation, and also sending a copy to the new (shadow) implementation for comparison, without affecting the user's experience. This provides crucial evidence (divergence, error rates, business outcomes) to inform your rollout decisions.

An End-to-End Invoice Migration Example

Let's integrate these concepts with a simplified, in-memory invoice generation example:

First, define the shared contract for invoice generation:

typescript type InvoiceInput = { orderId: string; subtotal: number; }; type Invoice = { orderId: string; total: number; }; interface InvoiceGenerator { generate( input: InvoiceInput ): Promise<Invoice>; }

Then, our legacy and migrated implementations:

typescript class LegacyInvoiceGenerator implements InvoiceGenerator { async generate( input: InvoiceInput ): Promise<Invoice> { return { orderId: input.orderId, total: input.subtotal * 1.21 }; } }

class MigratedInvoiceGenerator implements InvoiceGenerator { async generate( input: InvoiceInput ): Promise<Invoice> { const tax = input.subtotal * 0.21; return { orderId: input.orderId, total: input.subtotal + tax }; } }

To enable deterministic rollout, we can use a simple bucketing function. This ensures the same orderId always follows the same route based on a defined percentage:

typescript function bucketFor( value: string ): number { const sum = [...value].reduce( (total, char) => total + char.charCodeAt(0), 0 ); return sum % 100; }

function shouldUseMigrated( orderId: string, percentage: number ): boolean { return ( bucketFor(orderId) < percentage ); }

We'll also track basic metrics:

typescript const metrics = { legacyRequests: 0, migratedRequests: 0, mismatches: 0, };

Finally, an IncrementalInvoiceService combines dual execution, comparison, and routing:

typescript class IncrementalInvoiceService { migratedEnabled = true; rolloutPercentage = 10; constructor( private readonly legacy: InvoiceGenerator, private readonly migrated: InvoiceGenerator ) {}

async generate( input: InvoiceInput ): Promise<Invoice> { const legacyResult = await this.legacy.generate( structuredClone(input) ); const migratedResult = await this.migrated.generate( structuredClone(input) );

if (
  migratedResult.orderId !== legacyResult.orderId ||
  migratedResult.total !== legacyResult.total
) {
  metrics.mismatches += 1;
}

const useMigrated = this.migratedEnabled && shouldUseMigrated(
  input.orderId, this.rolloutPercentage );

if (useMigrated) {
  metrics.migratedRequests += 1;
  return migratedResult;
}
metrics.legacyRequests += 1;
return legacyResult;

} }

Executing this with a loop:

typescript const service = new IncrementalInvoiceService( new LegacyInvoiceGenerator(), new MigratedInvoiceGenerator() );

for (let i = 1; i <= 100; i++) { await service.generate({ orderId: order-${i}, subtotal: 1000 }); } console.log(metrics); // Example output: { legacyRequests: 89, migratedRequests: 11, mismatches: 0 }

This demonstrates running both implementations, comparing results for mismatches, and routing a percentage of traffic. If issues arise, service.migratedEnabled = false immediately rolls back to the legacy path. In production, careful handling of side effects (e.g., using isolated infrastructure for shadow paths) would be critical.

Designing Rollback and Data Considerations

Rollback must be designed before you need it. For routing-level migrations, it can be as simple as flipping a feature flag. However, rollback becomes complex with data format changes, new data writes, different events, or external system updates. This might necessitate backward-compatible schemas, compensating actions for external side effects, or reconciliation jobs. Understand when rollback is a simple flip versus when it requires a more involved recovery strategy.

Data migration is a beast of its own, distinct from application migration. It often involves careful planning around dual writes, data ownership, and ensuring both old and new systems can operate with evolving schemas. Treat it as a separate, critical problem.

The Role of AI: Assistance, Not Automation

Artificial intelligence tools can assist in incremental migrations, such as generating characterization tests to document legacy behavior, suggesting refactoring opportunities, or explaining complex code. However, it's crucial not to let AI turn an incremental migration into an automated big-bang rewrite. AI excels at code generation, but human oversight is essential for validating behavior, managing risk, and understanding the nuances of business logic.

Practical Takeaways

Incremental migration is about de-risking a complex process. By focusing on small, observable business capabilities, establishing clear boundaries, explicitly routing traffic, and constantly validating behavior, you transform a high-stakes cutover into a series of controlled experiments. This approach fosters continuous learning, builds confidence, and ensures you're always in a position to roll back if necessary.

FAQ

Q: What's the biggest risk of using a try-catch block for silent fallback to the legacy service during migration?

A: The primary risk is that it masks failures in the new, migrated implementation. If the new service consistently fails but silently falls back, users might not observe issues, but the migration itself isn't healthy. This hinders observability, prevents accurate error rate assessment, and can delay the detection of critical bugs in the new code, making progressive rollout decisions unreliable.

Q: How do you handle side effects when performing differential testing or running shadow traffic?

A: Handling side effects requires careful consideration. For differential testing during pre-production, you might use mock or isolated environments. For production shadow traffic, the shadow path needs to prevent actual side effects. This can involve using recording adapters, isolated infrastructure (e.g., a separate database or messaging queue for the shadow service), or mechanisms that log/simulate side effects without committing them to actual production systems. The goal is to compare potential behavior without duplicating real-world consequences.

Q: How do you determine when a migration slice is truly complete and the legacy path can be removed?

A: A migration slice is complete when the new implementation has handled 100% of the relevant production traffic for a sufficient period, consistently meeting or exceeding performance and correctness metrics compared to the legacy system. This includes observing business behavior, not just infrastructure metrics, to ensure business outcomes are correct. Once confidence is high, and rollback is no longer considered necessary for that capability, the legacy path and its supporting code can be safely removed.