The pitch is compelling: microservices enable independent deployment, team autonomy, and better scalability. The business case makes sense. The timeline looks achievable.
Then reality hits.
What was supposed to take 6 months takes 18. The budget triples. And somehow, the new system has problems the old one never had.
The Pattern
Healthcare.gov (2013)
A case study in architectural chaos
60
contracts
33
vendors
30%
user access rate
50K
crash threshold
Every large-scale rewrite has the same hidden cost:
Rediscovering decisions that were already made.
The Decision Rediscovery Tax
Your monolith didn't become a monolith by accident. It's the accumulated result of hundreds of architectural decisions:
- Why these service boundaries (or lack thereof)?
- Why this database schema?
- Why these cache strategies?
- Why these consistency guarantees?
Some were good. Some were bad. Some were good at the time but aren't anymore. But all of them had reasons.
Without documentation, you have three options:
Guess
Make the decision again, possibly wrong
Investigate
Spend hours/days understanding why
Copy blindly
Replicate patterns without understanding
All three cost time. Options 1 and 3 create risk.
The Numbers
Let's model a typical microservices migration:
Original Estimate
Actual (Undocumented)
Where Time Goes
Where Time Goes
Documentation outdated, key people left, code shows what not why
Edge cases fixed once, then forgotten. Discovered again in production.
Trying approaches that already failed. No one remembers why.
“Payments fail for orders over $10,000 from Canadian customers on weekends.”
Why? Some combination of fraud rules, payment processor limits, and timezone handling.
The Documented Alternative
What if decisions had been recorded all along?
Design Phase
Why boundaries exist, what was tried, which constraints valid
Build Phase
Known edge cases, consistency decisions, integration contracts
Migration Phase
Schema history, data quality decisions, known workarounds
With Documentation
Still more than original estimate, but less than half the undocumented version
The Strategic Debt Angle
McKinsey estimates technical debt consumes 40% of IT balance sheets. But migrations reveal something worse: strategic debt.
What Strategic Debt Looks Like
Migrations surface hidden architectural issues
Duplicated functionality
Services that do the same thing (no one knew)
Contradicting patterns
Different teams decided differently
Hidden dependencies
Organic growth, no governance
This debt doesn't show up in code quality metrics. It shows up in migration complexity.
Building Migration-Ready Architecture
You might not be migrating today. But someday, someone will. Make it easier:
Document decisions as they happen
- What was decided
- Why it was decided
- What alternatives considered
- What constraints drove it
10 minutes now vs days reconstructing later
Track dependencies explicitly
- What depends on what
- Why dependencies exist
- What would break if changed
Don't rely on code to show relationships
Record edge cases when discovered
- What's the case?
- Why does it happen?
- How is it handled?
Future maintainers will thank you
Keep constraints current
- Is this still true?
- Do we still need this?
- Has the tradeoff changed?
Review documented constraints quarterly
Pre-Migration Checklist
The Post-Migration Mandate
The best time to document architectural decisions was when they were made. The second best time is now—before the next migration begins.