👋 Hey {{first_name|there}},
You inherit a system, the docs are wrong, and someone wants a migration plan by Friday. This is how I learned to assess what's actually running before I commit to changing any of it.
Why this matters / where it hurts
You join a new team. There's a diagram pinned in the onboarding wiki. Four services, tidy arrows, everything in its right place. Two weeks in, you find a batch job called nightly_sync_v2 that's been running for four years. Nobody currently on the team remembers writing it. Somebody mentions in passing that if you disable it, the report the VP of Sales reads on Monday morning stops working. That's all the documentation there is.
That's brownfield. And in my experience, it's most of what architect work actually looks like. Green-field rewrites are the exception. The real job is almost always changing a system that's already running, already has users, and already has somebody depending on a behaviour nobody documented.
The failure pattern is depressingly consistent. A migration gets scoped off the wiki diagram. A timeline lands in a roadmap deck. Work starts. Then, slowly, the plan meets the system. An undocumented consumer shows up in the logs. A webhook starts failing quietly for a week before anyone notices. A year later, the migration is technically "done-ish," but the old system still can't be turned off because three things that were never in the plan still depend on it. You've now paid for the new system, kept paying for the old one, and shipped very little clarity to anyone.
In Lesson #47 on the Modular Monolith decision framework, we looked at choosing the shape of a system you're designing. This is the harder question: what do you do with the shape you already have, when the shape on paper isn't the shape in production?
🧭 The shift
From: We'll migrate this system to the new architecture.
To: We'll map what's actually running before we commit to anything.
The strangler fig pattern works, but only against an honest picture of the existing system. Textbooks show a clean old system gradually replaced by a clean new one. Production doesn't look like that very often. It has cron jobs nobody owns, a reporting database a BI tool reads directly, a service that was "decommissioned" last year but still gets traffic on Tuesdays.
When a migration stalls halfway through, you get the worst combination of both systems running at once, each carrying part of the truth. That's similar in feel to what we covered in Lesson #34 on the Distributed Monolith, except the mess here is historical rather than architectural.
A few defaults I'd offer, cautiously:
Every architecture diagram older than six months should be treated as a hypothesis. Worth checking. Not worth building a roadmap on top of.
The real dependency graph lives in production telemetry, access logs, and network traffic. The wiki tells you what somebody intended once. Production tells you what exists today.
Find the parts nobody owns, monitors, or tests before you promise to replace any of them. That's where most of the timeline overrun I've seen actually comes from.
🚀 Want the full architecture roadmap?
If you found this useful and you're not subscribed yet, I built something that might be worth your time. It's a free 5-day email crash course designed specifically for developers moving into architecture roles. One lesson per day, short enough to read over coffee, practical enough to apply the same week.
It covers the foundational shifts that most developers don't get taught: how to think in tradeoffs instead of "best practices," how to communicate technical decisions to non-technical stakeholders, and how to spot the architectural problems that don't show up until production traffic hits. Basically, the stuff I wish someone had walked me through when I made that transition myself.
No fluff, no upsell at the end. Just five days of focused, experience-based lessons.