Context relationships

Map how bounded contexts depend on each other in SpecsGraph, with upstream and downstream direction and patterns like customer/supplier and open host service.

Upstream and downstream

A relationship connects two contexts and says which way influence flows. The upstream context provides something the downstream context depends on: data, events or an API. When upstream changes, downstream feels it. Changes downstream rarely affect upstream.

At Northwind, Catalog is upstream of Orders. Orders needs Catalog's products, prices and stock levels to build a checkout, but Catalog does not care what Orders does with them. If Catalog renames a field, Orders has to adapt; the reverse is not true.

Direction describes dependency, not which way requests travel. Orders calls Catalog's API, and Catalog is still upstream.

Relationship fields

Field	What it holds
Upstream and downstream	The two contexts, in that order.
Patterns	One or more of the patterns below. An upstream pattern such as Open host service often pairs with a downstream one such as Anticorruption layer.
Description	What crosses the boundary and why, in a sentence or two.
Links	Requirements and decisions that depend on the relationship.

Relationship patterns

The patterns come from Domain-Driven Design context maps. Each one describes how the two teams and their models deal with each other.

Pattern	What it means	Use it when
Partnership	Two teams plan and ship related changes together. Neither side succeeds alone.	The contexts share a goal and the teams coordinate closely.
Shared kernel	Two contexts share a small piece of model or code, and both must agree before it changes.	Sharing a tiny piece, such as a money type, is cheaper than translating it. Keep it small.
Customer/supplier	Downstream is the customer: its needs shape upstream's plans, and upstream commits to what it provides.	Both teams can negotiate, usually because they are in the same organization.
Conformist	Downstream adopts upstream's model as it is, without translating it.	Upstream will not change for you, and its model is good enough for your needs.
Anticorruption layer	Downstream translates upstream's model into its own at the boundary, so upstream's terms do not leak in.	Upstream's model is awkward, unstable or owned by someone you cannot influence.
Open host service	Upstream offers a well-defined API or event stream that any downstream context can use.	Several contexts consume the same thing from one upstream.
Published language	A documented format for data that crosses the boundary, such as a versioned event schema.	You want the contract written down. It often pairs with Open host service.
Separate ways	The two contexts do not integrate at all. Each solves its own problem.	Integrating would cost more than it returns.

Northwind's relationships

The Northwind map has 9 relationships. Each row reads upstream first.

Upstream	Downstream	Pattern	What crosses the boundary
Identity	Orders	Open host service	Customer ID and sign-in state from Identity's API.
Identity	Billing	Open host service	Customer ID and billing contact.
Catalog	Orders	Customer/supplier	Products, prices and stock levels used at checkout. ORD-12 depends on this edge.
Orders	Billing	Partnership	Confirmed reservations, then the request to capture payment. BIL-04 depends on this edge.
Orders	Fulfilment	Published language	An order placed event with line items and the delivery address.
Fulfilment	Notifications	Conformist	Shipment events that Notifications turns into messages for the Customer.
Billing	Notifications	Conformist	Receipts and failed payment notices.
Orders	Analytics	Published language	Order events for reporting.
Catalog	Analytics	Anticorruption layer	Catalog changes, translated into the product model Analytics reports on.

Notice what is missing. Catalog and Identity have no edge between them: they go separate ways, and the map does not need to say so. When a missing edge is a deliberate choice, record it in the decision log so nobody adds the integration later without knowing why it was left out.

Relationships on the map

On the system map, each relationship is an edge with an arrow from upstream to downstream. Select an edge to see its patterns, description and linked requirements. When you zoom into a context, its neighbors stay visible around it, so you can see what it depends on and what depends on it.

Follow the edges when you review a change. A proposal that changes how Catalog reports stock levels reaches Orders and Analytics downstream, and the edges show both before anyone approves it.

Changing relationships

Relationships change through proposals, like contexts and requirements. Agents read them with get_context, which returns a context's relationships along with its services and requirements, and draft changes with propose_structure_change.

Each context's relationships are published in its context.md file, for example specsgraph/contexts/orders/context.md for Orders. Spec files in your repository shows the format.

Links between requirements, terms and decisions

Relationships connect contexts. Finer links connect single nodes, inside a context or across two. They are what a proposal's diff follows when it shows linked nodes the proposal does not edit.

Link	From and to	How it is made
Term	A requirement, scenario or context purpose to a glossary term.	Automatically, from the words in the text. See Automatic linking.
Actor	A requirement or scenario to an actor.	Automatically, from actor names in the text and steps.
Related requirement	A requirement to another requirement, in any context.	Added while editing the requirement in a proposal, or by an agent with `propose_requirement`. Published as `related`.
Decision	A requirement to the decision that explains it.	Added while editing either one, or by an agent with `record_decision`. Published as `decisions`.
Supersedes	A decision to the decision it replaces.	Set on the new decision. Both records show the link.
Task	A workstream task to requirements and proposals.	Added on the task. See Workstreams.

A related link has no type of its own. It says two rules depend on each other, so a change to one brings the other into view in the review, as BIL-04 does for ORD-12.

Next steps

Bounded contexts and subdomains for the nodes these edges connect.
The system graph for how relationships appear on the map.
Domain-driven and behavior-driven foundations for more on context maps.