When two bounded contexts in a system exchange data — say, an Orders context and a Shipping context — how do you determine which one is upstream and which is downstream, and why does getting that direction right matter for how the two teams should work together?

## What the label answers Upstream/downstream (`U/D`) is the directionality label attached to every edge on a context map, and it answers a single practical question: when these two bounded contexts need to agree on something — a message shape, an API contract, a shared concept — which side does the adapting? The mechanism for determining it is a diagnostic question applied per relationship, not a global rule: **if this integration needs to change, which side is expected to change its own model to accommodate the other?** - The context that keeps its model stable and is accommodated by the other is **upstream** (`U`). - The context that adapts, absorbs, or translates to match the upstream's model is **downstream** (`D`). Direction is drawn per edge, and it's entirely possible — common, even — for a single context to be upstream of one neighbor and downstream of another; there's no single 'core' context that is upstream of everything. ## Why it is an organizational fact, not only a technical one Crucially, this determination is not purely a technical judgment about which system's data model is 'more correct.' It is frequently an organizational fact. A context becomes upstream: - because its owning team **ships first** and other teams build against what already exists; - because it's a **platform capability** many other contexts consume, so changing it has a large blast radius and is therefore resisted; - or simply because that team has more **organizational leverage**, an earlier deadline, or executive sponsorship, and other teams are told to adapt to them regardless of technical elegance. This is one of the places DDD strategic design explicitly acknowledges that software structure follows organizational structure — a context map that only tracked technical data flow and ignored who has the political power to resist change would misdescribe how the system actually evolves. ## How the two teams operate together The reason getting U/D direction right, and making it explicit, matters is that it sets concrete expectations for how the two teams operate together. An upstream team, once its downstream dependents are known, takes on an implicit obligation; a downstream team, knowing it's downstream, plans differently and may choose to insulate itself. | Side | How that team operates | |---|---| | **Upstream** | Gives advance notice of breaking changes, considers versioning or backward compatibility, and treats its public contract as something other teams have built real systems against. | | **Downstream** | Budgets effort for adapting to upstream changes, treats the upstream's schema as something outside its control, and — if the relationship is adversarial or the upstream is unresponsive — may choose to insulate itself with a translation layer rather than let upstream churn propagate directly into its own model. | ## The trade-off The trade-off in this exercise is that direction is not always comfortable to declare truthfully. It's tempting for a map to describe an idealized, mutually respectful relationship when the lived reality is that one team unilaterally dictates and the other has no real say — but a context map that papers over that asymmetry to be diplomatic loses its main value, which is making the actual power dynamic visible so it can be managed rather than silently suffered. ## Failure modes Failure modes show up in a few recognizable ways. 1. **Nobody declared it.** The most common is a relationship where direction was never explicitly agreed, so both sides assume they're the ones with authority; a schema changes, the other side breaks, and a blame dispute follows, when the real problem was that nobody had declared, ahead of time, who was supposed to adapt to whom. 2. **Declared one way, enforced the other.** A second failure is direction that's technically declared one way on paper but organizationally enforced the other way in practice — e.g., a legacy system is nominally 'downstream' of a shiny new context on the map, but in reality the legacy system's owners refuse to change anything, so the new context ends up doing all the adapting regardless of what the diagram says. When that happens, the map is lying, and teams that trust it will misallocate effort. 3. **Direction flips over time.** A third failure is instability of direction over time: a context that starts downstream may, as it matures and gains its own consumers, need to flip to upstream for some of its relationships — if the map isn't revisited, decisions get made against a direction that no longer reflects reality. ## A concrete example A concrete example: in the Orders/Shipping case, if Orders publishes an `OrderPlaced` event and Shipping subscribes and adapts its own model to whatever shape that event takes, **Orders is upstream and Shipping is downstream** — meaning Orders' team owes Shipping's team advance warning before changing that event's schema, and Shipping's team should expect to keep adapting rather than ask Orders to restructure around Shipping's needs.