Writing1 min read

Architecture Notes

Refactoring a Monolith Safely

We needed a seam, not a rewrite.

We needed a seam, not a rewrite

Leadership asked for a split before a major release. The monolith mixed billing and notifications in one folder.

A rewrite would have frozen the product. We needed a smaller move.


Weekly releases, thin tests

Releases were weekly. Tests were thin on the billing edge. Every change touched unrelated imports.


Big-bang extraction pressure

The team wanted to extract everything at once. Without a seam, behavior comparisons were impossible.


Find the seam first

Find the seam with tests. Wrap old code behind a narrow interface. Ship while you split.

Edges first: routes and handlers before deep domain moves.


Import boundary

Monolith seam
Before and after
// before
import { sendReceipt } from '../notifications/email';

// after
import { BillingNotifier } from './billing-notifier';

Ship while you split

Refactor in slices that can stop halfway without breaking prod. Momentum beats a perfect diagram.


References