The pipelines we ship fit on one screen. Not the marketing diagram — the actual code path a request takes, top to bottom, with every hop named. That constraint is a design stance, not an aesthetic, and we pay real costs to hold it.
What "readable" means here
A readable pipeline is one where a client engineer who joined yesterday can answer three questions without asking us:
- Where does the request enter, and where does it exit?
- What happens at each hop, and where is that hop's code?
- If a step fails, where does the failure show up in the logs, and what is the next step they should look at?
If any of those takes more than a minute on a fresh laptop, the pipeline is not readable. It may be clever, performant, or well-tested — but it is not readable, and that is the property we optimize for (Class C — observable on any engagement by handing a fresh engineer the repo and a stopwatch).
The single-screen constraint is the forcing function. A pipeline that does not fit on one screen has either grown too many hops or is hiding them behind names that do not describe what they do. Both problems get fixed the same way: rewrite the orchestration so the hop count is honest.
What we trade away
Readability is not free. The trades are real and we name them up front, so clients can decide whether they want them.
We trade some abstraction for some duplication. A clever framework that handles retries, fan-out, and rate-limiting in one decorator is more compact than three lines of explicit code at each call site. We prefer the three lines. The decorator hides where the retry actually happens; the three lines tell you exactly. At 3am, "exactly" is worth more than "compact."
We trade some peak throughput for some debuggability. A pipeline written for maximum throughput often batches and fans out in ways that make a single request hard to trace. We start with the version where every request has a clean linear trace, and add concurrency only where load tests prove we need it — explicitly, with the concurrency points marked.
We trade vendor convenience for portability. A managed orchestration platform will run your pipeline and give you a pretty graph. The cost is that the pipeline now lives inside the platform. We write it in plain code in the client's own repository, with a runbook for running it on a laptop, a CI runner, or a small box. The graph goes in the README.
What this looks like in practice
A recent engagement: a content pipeline that pulls from three sources, runs each through a quality check, drops the ones that fail, formats the survivors, and writes them to a destination. The previous vendor had built this on a workflow platform with twelve nodes, four sub-flows, and a custom DSL for the quality check.
We rebuilt it as a single Python file, 180 lines, five named functions, one main loop. The quality check is a function the client's editorial lead can read out loud. The retries are three lines at the source-fetch call. Errors write to a local log in a format their existing alerting already understood. The whole thing fits on one screen if you fold the imports.
Total time from intake to production: nine days. Platform fees: zero. Dark dependencies (Class C, defined in /no-dark-dependencies): zero. The trade: we gave up the platform's built-in dashboard. The client did not care — they already had logging infrastructure the new pipeline wrote into. The dashboard was a feature for the vendor, not for them.
Why this is a design stance, not a technique
Plenty of teams write readable code. We are claiming something narrower and more demanding: every engagement starts from the assumption that the pipeline must be readable end-to-end by someone we have not met, and every decision that conflicts with that assumption gets surfaced as a trade for the client to decide, not a default we make on their behalf (Class E — this is consistent with the long-standing software engineering literature on legibility, maintainability, and operator burden; we are not inventing the value, only making it the binding constraint).
The opposite stance — "ship the magic box, document the API, trust the abstraction" — produces systems that demo well and become unmaintainable the day the original team leaves. We have cleaned those systems up enough times to treat prevention as a contract term.
What to ask before your next pipeline gets built
Three questions are usually enough:
- Can a new engineer read the full request path on one screen on day one?
- Which hops are inside a framework, and which are in plain code I can edit?
- If the vendor disappeared tomorrow, would the pipeline still run? Show me.
If those answers are vague, the pipeline is a magic box. Magic boxes are fine until they aren't.