From Monolith to Microservices, Safely

Nobody sets out to write a monolith. It accretes until the day a three-line change takes three weeks and the team stops volunteering for the hard parts. The instinct is to rewrite. The instinct is wrong.

Draw the seams before you write a line

The whole game is where you cut. A good seam follows a business capability with a clean data boundary; a bad seam follows the org chart. We start by mapping the domain, not the code, and we look for the capability that is painful, bounded, and low-risk to run in parallel.

export async function route(req: Request) {
  const useNew = await rollout.flag('checkout-v2', { slice: req.headers.get('x-capability') });
  return (useNew ? checkoutV2 : legacy).handle(req);
}

Know when to stop strangling

The pattern is a means, not a religion. When the last painful capability is gone, stop. Leave the quiet old core alone, document the boundary, and spend the saved energy on the next thing that actually moves a metric. That restraint is the mark of a team that ships.

If you cannot run the old and the new at the same time, you do not have a migration — you have a flag day. Flag days are how careers end.