Who has to know before this changes?
The Clinical Records team at a chain of veterinary clinics wants to change how a vaccination is recorded. Today it is a treatment line with the product name typed in by the vet; the new model gives each vaccine a product code and a validity period. Inside their own bounded context it is a sensible change. The team lead's first question is about everything outside it: who has to know? The Reminders context reads vaccinations to work out when to write to owners. Pharmacy checks doses against the same animals. Insurers download treatment histories. Whether any of them would break, or would have to be consulted, is written down nowhere.
A context map is where it gets written down: every context, and the agreement that governs each seam between two of them, meaning who depends on whom and whose model wins. What a context is and where its boundary goes belong to Bounded Context; how the business itself divides into parts belongs to Subdomains & ubiquitous language. This article is about the lines between the boxes.
The relationships a context map is drawn with. On a Grid each one is a node, placed between the contexts it relates.
Upstream means influence, not data
The first thing the map records at a seam is direction. A context is upstream of another when its changes affect the other's success and the reverse does not hold; the other is downstream. Clinical Records is upstream of Reminders: change how vaccinations are stored and reminders stop going out, while a change inside Reminders leaves consultations untouched.
That is not the direction of the data. Every stock order travels from Pharmacy to its wholesaler, yet the wholesaler is upstream: it sets the product codes and the order format, and Pharmacy adapts when they change. Draw arrows by where the data goes and the next catalog change comes as a surprise. The clinics have no leverage over a wholesaler with thousands of customers, and its model is good enough, so Pharmacy's purchasing uses it as it is; that is a Conformist relationship, the subject of Conformist.
A customer the supplier listens to
Reminders is in a better position. It needs a next due date the vet can set by hand for animals on an unusual schedule, and it cannot add that field to Clinical Records itself, but the two teams work for the same company. They agree on a Customer-Supplier relationship: the downstream team is the customer, and its needs go into the upstream team's planning, negotiated and scheduled like any other work. Reminders also writes automated acceptance tests for what it relies on, and the Clinical Records build runs them, so a change that breaks what those tests cover fails before release. For this seam, the opening question has an answer: the new vaccine model has to pass Reminders' tests, and the two teams talk first.
The arrangement lasts only as long as the supplier keeps honoring it. Suppose Clinical Records is moved onto a large rewrite: Reminders' requests wait for months, and its acceptance tests are switched off because they slow the rewrite down. The map still says Customer-Supplier, and it is wrong. Reminders is now where Pharmacy stands with the wholesaler, choosing between taking each new upstream model as it comes and protecting its own with a translating layer at the seam, an Anti-Corruption Layer. Which to choose is the question Conformist works through. Whichever it is, the map has to change with it, or it tells the next team to rely on a promise that is no longer kept.
When neither side can wait on the other
That failure is the risk of any upstream-downstream seam: the downstream's progress depends on another team's priorities. Appointments and Clinical Records are building video consultations together, and there the risk is unacceptable. The booking needs a consultation type the clinical side understands, the consultation record needs the call link the booking created, and neither half ships alone. Neither team is upstream, so they choose a Partnership: they plan together, work out the integration as they go, and release together, and when one slips, both slip. The cost is a planning cycle shared with another team, a commitment that does not stretch to many teams; once video consultations settle, the seam can relax into something with less ceremony.
Pharmacy has the same problem with a narrower scope. Its dose check needs the animal's weight, dated and in a known unit. A check that waits on a supplier's backlog is a safety problem, and a Partnership over everything would tie two teams that otherwise change independently, so the two teams share only that piece. A Shared Kernel is a small part of the model, with its code, that two teams agree to share and that neither changes without consulting the other; here it is the animal profile with its dated weighings and allergies, tested by both teams on every change. Every line in it is a line neither team can change alone, which is why it stays small. Vaccinations are not in it and Pharmacy reads nothing else from Clinical Records, so the opening's change needs nothing from Pharmacy.
One door for many downstreams
Customer-Supplier works while the customers are few. Pet insurers want claim evidence too, and with nine of them Clinical Records would be planning around nine sets of needs and keeping nine custom exports, each liable to break whenever the Clinical Records model changes. An Open Host Service replaces them with one protocol: a single, documented way into the upstream context, open to anyone who needs to integrate, extended when several consumers share a new need. A consumer with an unusual need translates on its own side, or gets a one-off translator, so the shared protocol stays simple.
The protocol speaks a documented format kept apart from Clinical Records' internal model, a Published Language: the language is what is exchanged, the host service is how it is offered, and Published Language is about the format itself. Because the two are separate, the vaccination change reaches insurers only if the team decides to add it to the format, provided Clinical Records keeps filling every field the format already promises, with the same meaning. The price is that the protocol is now a promise. Renaming a field in one release would break every insurer still reading the old name, so old and new versions run side by side for a while, as API versioning & backwards compatibility describes.
Seams with no agreement
After all these costs, the cheapest seam can be none. The grooming salons book baths and trims in their own app, and need from Appointments little more than a name and a phone number. The teams choose Separate Ways: no integration, and the receptionist types the phone number twice. The price is records that disagree and a harder start if the business ever wants one view of each customer. Marking it on the map keeps someone from later filling the gap with a quick query into the other team's database.
The clinics the group acquired run a fifteen-year-old practice-management system in which appointments, invoices and medical notes share the same tables. There are no separable models inside it to map, so the map draws one boundary around it and labels it a Big Ball of Mud, a warning not to model inside it or let it leak out. Where Clinical Records imports histories from it, the seam gets an Anti-Corruption Layer.
Arrows run from upstream to downstream through the relationship that governs the seam. Partnership, Shared Kernel and Separate Ways have no direction, so their lines have no arrowhead.
A map of how things are
Read the opening question against this map and it has an answer: Reminders is consulted and its tests have to pass, Pharmacy need not be asked, and the insurers see the change only if the format does. That answer holds only while the map is true. It records relationships as they are, including which team actually answers whose requests, and a map drawn as the architects would like it gives confident wrong answers. Redraw it when teams are reorganized or a supplier is pulled onto other work, because that is when relationships change.
Your own map
The Context Mapping Challenge has you draw one for a business of your choosing. Draw each relationship as a node between the contexts it governs, with arrows leaving the upstream side. Its 14-node limit is tighter than it looks: four contexts plus the seven relationship nodes it asks for already take eleven. The part worth the effort is the reason behind each choice. For every seam, ask what happens to the downstream when the upstream changes a field, and whether the relationship you drew is one the two teams would actually keep.