[Deep Dive #20] Monolith Bearings - discussion
We're doing a slow split-the-monolith effort and I'm trying to avoid the common trap where boundaries are just folder structure with no runtime truth.
What bearings do you actually use to keep boundaries real (route surfaces, adapter layers, signals/evidence)? How do you migrate a route to a new boundary without breaking deep links and back/forward behavior? And what do you do to keep boundary decisions from turning into a docs-only story?
Comments (10)
Back to latestIf the boundary isn't observable at runtime, it isn't real. Otherwise you'll still have cross-boundary coupling, just with nicer folders.
Our best bearing was the route contract itself: stable surface keys + signals that prove which boundary owns what.
Related: Architecture Guides and Migration Runbooks (Deep Dive #8).
We made boundary ownership explicit in signals during migrations:
ts
doc.write('boundarySignal', { surface: 'Orders', owner: 'billing-service', contract: 'v3' });
doc.write('adapterSignal', { adapter: 'legacy->new', version: 'v2', aligned: true });It sounds ceremonial, but it made code review and incident triage much calmer.
Counterpoint: signals can give a false sense of boundary purity.
We also kept a no-cross-boundary-imports rule, because runtime signals won't catch everything.
Agree. I like signals for the runtime story and tooling rules for the static story.
The worst case is boundary exists in docs, but not in build or runtime.
Yep. You need both or the boundary will leak through a side door.
Deep links were the forcing function for us. If a boundary change breaks a deep link, the migration isn't done.
We migrated file routes last, motion first.
Once component motion and route surfaces were stable, rewriting file route maps was mostly a mapping exercise with signals to catch drift.
We had a monolith split that created two competing sources of truth for a while.
The only thing that made it survivable was alignment signals plus a clear delete criteria in the runbook.
If the route contract includes contractVersion and the shell renders it, you can move boundaries without scaring everyone every deploy.
tsx
const doc = useRouteDoc('orders');
return (
<div
data-contract={doc.read('contractVersion')}
data-boundary={doc.read('boundarySignal')?.owner ?? 'unknown'}
/>
);When boundaries are real, support can tell from a signal which system to page. When boundaries are fake, every incident is a guessing game.
A boundary that can't be asserted in tests isn't a boundary. Signals give you a cheap way to assert it without importing internals.