MPY.log/entry-012: Making the Implicit, Explicit

Software systems rarely fall apart because one piece of code is wrong. They fall apart because the connections between things aren’t clear.

Different teams discuss the same concept, but have different meanings. Different systems integrate but assume too much. Different services evolve but step on each other’s toes.

Not because people are careless. But because the boundaries are invisible.

Where Complexity Hides

Ask three teams what a “customer” is:

• One says it’s a user with a login.
• One says it’s someone who’s paid.
• One says it’s anyone in the CRM.

All technically correct. All slightly different. And those differences? They quietly break APIs, reports, features, and trust.

This is what happens when bounded contexts collide without coordination.

And this is where context maps help.

What is a Context Map?

A context map is not a diagram. It’s a lens for seeing how your systems, teams, and languages interact.

Every team has its bounded context, its model, terms, and assumptions. Context maps make these explicit.

They don’t judge. They reveal.

You don’t need one perfect model. You need to understand where models differ, and design for it.

When to Use Context Maps

Use one when:

• You’re unsure who owns what
• A change in one team breaks another
• Different systems model the same thing in conflicting ways
• Terminology causes subtle misunderstandings
• You’re scaling teams, rewriting systems, or integrating with others

Context maps help you:

• Avoid accidental coupling
• Align on what’s shared vs. local
• Clarify ownership
• Design for collaboration instead of conflict

What It Looks Like in Practice

Start simple:

1. List the systems or teams
2. Write down their key concepts (e.g. “customer”, “plan”, “transaction”)
3. Note what each system calls them and how they define them
4. Draw connections:

Then label the relationships:

• Partnership — mutual evolution
• Customer/Supplier — one relies on another’s model
• Conformist — one side must follow the other
• Anticorruption Layer — translation layer to protect your model
• Big Ball of Mud — no clear boundary or contract

You don’t need a diagramming tool. You need honest mapping of how things actually work.

One Thought to Leave With

Most architectural pain lives in what we never bothered to say out loud.

Context maps don’t simplify the system. They surface the reality we’ve been working around.

And once you can see the shape of the problem, you can start to shape the solution.

Coming Up Next

MPY.log/entry-013: Protecting Clean Systems from Messy Ones

How to shield your system (and your sanity) when integrating with legacy or third-party models.

Have you ever sketched out how things connect and realised that’s the issue? That was a context map in disguise.

Let’s log it together.

Until next log,

—MPY