Upstream and Downstream Are Not Directions - piljoong.dev

Contents

Contents

Upstream and Downstream Are Not Directions<br>piljoong<br>included in categories Engineering Architecture<br>2026-06-11 2026-06-11 1270 words<br>6 minutes

Contents

The incident review started with a sentence that sounded ordinary.<br>&ldquo;The downstream service returned bad data.&rdquo;

Everyone knew what the speaker meant.<br>For about thirty seconds.<br>Then the conversation started to split.<br>The display team was talking about the pricing service they called during page rendering. From their point of view, pricing was downstream. The request left the display path, crossed a service boundary, and came back with price data.<br>The pricing team heard something different. They thought of themselves as upstream because they produced the data the display layer consumed. The price came from their system. The display page was downstream of that data.<br>The logistics team had a third interpretation. They were looking at the end-to-end commerce flow: discovery, display, checkout, payment, fulfillment, settlement. In that map, display was upstream of checkout, checkout was upstream of fulfillment, and fulfillment was downstream of almost everything before it.<br>Nobody was being careless.<br>The word was doing too much work.<br>That should not have surprised me as much as it did.<br>Software engineering runs on metaphors. We talk about layers, pipelines, streams, queues, ownership, contracts, boundaries, and gateways because the real thing is invisible. A program has no physical layer. A service does not literally own a field. A queue is not always a line of people waiting at a counter.<br>The metaphors work because they compress a mental model. They fail when that model is missing.<br>Extreme Programming had a practice called &ldquo;system metaphor&rdquo;: a simple shared story that helped customers, programmers, and managers talk about the system in the same language. The important part was not the metaphor itself, but the shared model it carried.<br>Upstream and downstream are the same kind of tool. They are river words, but a river metaphor only helps if everyone knows which river they are standing in.<br>The Case<br>Imagine a listing page in a marketplace.<br>It renders a set of items. For each item, the page needs display metadata, availability, inspection status, price, shipping promise, and whether the item is eligible for a promotion. The page itself is not the source of truth for most of that, so it calls several services:

text

listing-page<br>-> catalog<br>-> pricing<br>-> inventory<br>-> promotion<br>-> shipping-promise<br>One afternoon, some items show the wrong delivery promise. They appear eligible for next-day delivery even though inspection has not completed.<br>During triage, someone says:<br>&ldquo;The downstream service sent us the wrong status.&rdquo;

That sounds clear enough. The listing page called another service, and that service returned bad data.<br>A few minutes later, though, the investigation gets awkward. The shipping-promise service did not invent the status. It read inspection state from another feed, and that state was delayed because the warehouse system had not finished processing the item. The display page was showing a value derived from a chain of facts, not a fact owned by the service it called.<br>Now the team has at least three directions in play.

text

Call flow:<br>listing-page -> shipping-promise -> inspection-feed

Data flow:<br>warehouse -> inspection-feed -> shipping-promise -> listing-page

Business flow:<br>discovery -> display -> checkout -> payment -> fulfillment<br>Which one is upstream?<br>The answer depends on the noun you forgot to say.<br>Upstream of What?<br>I used to treat upstream and downstream as obvious words. They are not. They only become useful after you name the flow, or less formally, after you name the river.<br>If you mean call direction, the service you call is downstream from the calling service. If the listing page calls pricing, pricing is a downstream dependency of the listing page.<br>If you mean data origin, the producer is upstream of the data consumer. If pricing owns the price, pricing is upstream of the listing page for that field.<br>If you mean failure propagation, the failing dependency may be upstream in the causal chain even if it is downstream in the call graph.<br>If you mean business flow, the product listing may be upstream of checkout, and checkout may be upstream of fulfillment.<br>If you mean state ownership, the source of truth is upstream of every derived view.<br>All of those uses are defensible.<br>That is the problem.<br>The Word Hides the Axis<br>The dangerous part is not that engineers use different flows. That happens. The dangerous part is that the same word can make people feel aligned before they actually are.<br>In the listing incident, &ldquo;downstream service&rdquo; sounded precise. It was not. It collapsed several questions into one phrase:<br>Which service did we call?<br>Which system owned the incorrect field?<br>Which system derived it?<br>Which workflow step...