How to draw a data pipeline diagram: start at the sinks and walk backwards

Write down what the pipeline produces: the executive dashboard, the feature table the model reads, the reverse ETL sync into the CRM, the API a partner calls. Those are the reasons the pipeline is funded, and they are the only boxes most of your readers will recognize on sight. Placing them first means the diagram is guaranteed to answer the question people came with, which is usually some version of where does this number come from.

Then walk backwards, one hop at a time, asking what feeds this. Stop at the first system your team does not own. That boundary is the natural left edge of the diagram, and it doubles as the edge of your incident surface: everything left of it fails without asking your permission.

The backwards walk has a useful side effect. Anything that turns out to feed nothing gets found. A staging table with no descendant is either dead code paying for storage or an undocumented dependency somebody queries directly, and both are worth discovering before you publish the picture.

A bare arrow between two boxes carries almost no information. The same arrow labelled Parquet, hourly, around 4 GB per day carries the format, the schedule, and the order of magnitude, which covers most of what a reader needs in order to reason about a delay or a cost spike.

Three labels do the heavy lifting. The transport says how bytes move: bulk API extract, CDC stream, file drop on object storage, JDBC pull. The cadence says when: continuous, every 15 minutes, nightly at 02:00 UTC. The volume says how much, as an order of magnitude rather than a measured figure, because nobody is going to keep a precise number current and a wrong precise number is worse than an honest rough one.

Keep the labels on the edges, not in the node names. Node names should stay the real names of real objects, so a reader can copy one into a search box and find the thing.

Salesforce  --[bulk API, nightly 01:00 UTC, ~2M rows]-->  raw.salesforce_*
Postgres    --[CDC via Debezium, continuous, ~800 events/s]-->  raw.app_events
raw.*       --[dbt run, hourly, ~40 models]-->  staging.*
marts.revenue_daily  --[scheduled extract, 06:00 UTC]-->  Looker "Revenue" board

Decide the containers first. The common split for a pipeline is source systems, ingestion, storage layers, transformation, and serving, drawn left to right as five zones. The alternative split is by ownership, one zone per team, which is the right choice when the diagram exists to settle an argument about who is on the hook for what.

Zones do more than tidy the layout. A zone boundary is where a handoff happens, and a handoff is where a contract should exist: a schema, an agreed cadence, a named owner. Drawing the boundary first makes the missing contracts visible, because you end up with an arrow crossing a boundary that nobody can name the owner of.

Inside a zone, keep the node count honest but bounded. Forty ingestion connectors become one node reading 40 connectors, with the list living in the written doc. Fifteen dashboards fed by one gold table become one node reading 15 dashboards. The point of the diagram is the shape, and repetition is not shape.

Composing a diagram from an empty canvas is slow. Correcting one is fast. Describe the pipeline in one paragraph of plain language, including the source systems, the ingestion tool, the warehouse, the transformation layer, and the consumers, and let Datadef produce the first canvas with real vendor marks on the nodes, drawn from a registry of over two thousand icons that includes 438 AWS, 624 Azure, and 226 GCP services. Then fix what it got wrong, which is usually one or two hops and a name.

From there it is a normal editable canvas: rename nodes to your real table names, drag boxes into the mental order your team uses, relabel the edges with your real cadences, and add zones. Export as PNG or JPEG for a slide, or take the live embed URL so a README or a Confluence page renders the current version instead of a screenshot of last quarter.

If you work in an editor with an agent, the same thing happens over MCP: the agent reads the repository it already has open, calls create_diagram, then corrects the result with the canvas tools without you leaving the terminal. The server exposes 36 tools in total, nine outcome-level ones and 27 canvas_* edits, and answers initialize and tools/list without credentials, so a client can inspect the surface before anyone issues a key.

Draw our data pipeline as an architecture diagram.
Sources: Postgres (CDC), Salesforce (nightly bulk API), S3 event drops.
Ingestion: Fivetran into Snowflake RAW.
Transformation: dbt, staging then marts.
Serving: Looker dashboards, a Hightouch sync back to Salesforce, a feature table for the churn model.
Label every arrow with cadence. Group sources, ingestion, warehouse, and serving as zones.

• Data pipeline diagram generator
• What a good pipeline diagram shows
• Sources and sinks on a pipeline diagram
• How detailed should a pipeline diagram be
• Data pipeline documentation