Diagram Guide

Warehouse diagrams for stakeholders and for engineers: two drawings, one source

By the engineer who builds Datadef, from client work on data platforms · Reviewed August 21, 2026

The diagram that gets a budget approved and the diagram that helps somebody debug a failed load at 2am are not the same picture, and trying to make one drawing do both produces something that fails at each. The useful move is to accept two versions with different rules, built from the same underlying model so they cannot contradict each other.

Try it free
7 min readFor data leads who present the same platform to a steering committee and to their team

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

194/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

Why one diagram cannot do both jobs

A stakeholder is deciding whether to fund something, whether to trust a number, or whom to ask when a report looks wrong. The questions are where does this data come from, what does it feed, who owns it, and how fresh is it. Seven to twelve boxes answer all four. Anything past that spends attention without adding an answer.

An engineer is changing something and needs to know what will break. The questions are which job writes this table, on what schedule, from which source, in which format, and what reads it downstream. That needs the physical objects, and a version with fewer than fifty nodes would be lying by omission.

The common compromise, one diagram at medium detail, gives the stakeholder more than they can hold and the engineer less than they can use. It is the diagram that ends up on a wiki page and gets referenced by nobody.

What belongs on the stakeholder version

Name boxes after what they answer, not after the technology inside them. Customer 360, revenue reporting, and product usage analytics communicate; gold schema and silver layer do not, unless the audience already works with the platform daily.

Put ownership and freshness on the boxes. A steering committee question that comes up every time is who is responsible and how current is this, and answering it on the diagram removes a slide.

One arrow per meaningful flow, and label the arrow with the business event, not the mechanism. Orders land nightly is more useful than Kafka to Delta.

Keep the vendor icons where the vendor is part of the decision, for example when the committee is approving a platform, and drop them where they are not. Real icons help recognition, but a diagram covered in logos reads as a procurement list rather than an architecture.

Twelve boxes is the ceiling. If the platform genuinely needs more, that is a sign the stakeholder version should show domains, with a separate drawing per domain for the teams that own them.

What belongs on the engineering version

Physical containers, exactly as they are named in the platform: catalog, database, schema. Zones make this readable, one zone per container, so that the mental map matches what somebody types in a query.

Jobs and schedules, named. A pipeline node carries its technology and its schedule as fields, so the hop between two tables reads as dbt, 0 2 * * *, and validate_canvas raises a vague-pipeline warning for any pipeline node that specifies neither. That is three questions answered that would otherwise be three clicks in an orchestrator.

Grain sentences on the fact nodes and history policy on the dimension nodes. These are the two annotations that stop the most defects, and they cost one line each.

Column-level lineage for the columns that matter, not for all of them. Nobody needs a thousand column edges, but the five fields that feed the board metric should be traceable end to end from the diagram.

Failure surface: retries, dead letter destinations, and the reprocessing entry point. The engineering diagram is the one somebody opens during an incident, so it should carry what an incident needs.

Same platform, two drawings

  STAKEHOLDER (9 boxes)      ENGINEERING (54 nodes)
  --------------------       ----------------------
  Orders (Shopify)           raw.shopify_orders
    |  orders land nightly     |  fivetran, hourly
    v                          v
  Customer 360               staging/  6 models
    owner: Data Eng          int/      4 models
    fresh: 06:00 UTC         marts/    dim_customer
    |                                  (type 2: segment,
    v                                   billing_country)
  Revenue reporting                    fct_order_lines
    owner: Finance                     (one row per order
                                        line, per shipment)

  Same canvas. The left column IS the right column with
  every zone collapsed.

Two views, one source, no contradiction

Build both on the same Datadef canvas rather than in two files. Groups collapse, so an engineering diagram with fifty nodes becomes an eight-box stakeholder view by collapsing each zone, and the two versions cannot disagree because there is one model underneath. Zones, labelled edges, and node descriptions carry the detail that gets hidden or shown.

The canvas will also tell you when the engineering view has stopped being a diagram. Past thirty data nodes it raises a dense-canvas warning, on the reasoning that a bigger picture gets searched rather than read, and it stays a warning rather than an error because on an engineering view the detail is often exactly the point. A companion tool lists which near-identical groups would be clearer collapsed, and it only lists them: the collapse itself is a separate call somebody makes on purpose, because deciding what a reader may stop seeing is not a decision to automate.

Publish them differently. The engineering view belongs in the wiki and the repository README as a live embed, one markdown line that always renders the current version and needs no account to view. The stakeholder view is usually exported to PNG or JPEG for a deck, which is fine because a deck is a snapshot of a moment by design.

The half of the picture that comes from code should come from code. Connect the repository that declares the platform and the daily sync regenerates the diagram and its architecture.md from the branch, so the engineering view keeps up without anyone maintaining it, and the stakeholder view inherits that accuracy. Teams that present monthly find this is the difference between a slide they trust and a slide they check first.

Review the stakeholder version with a stakeholder

The fastest test is to hand the twelve-box version to somebody outside the data team and ask them to say what the platform does. If they cannot, the boxes are named after the technology. Working through this live is easier in a shared canvas than over screenshots.

FAQ

How many boxes should an executive data architecture diagram have?

Seven to twelve. That is enough to show where data comes from, what it feeds, who owns it, and how fresh it is, which are the four questions a non-technical audience actually asks. Past twelve, attention is spent on reading rather than on deciding.

Should a stakeholder diagram use vendor logos?

Only when the vendor is part of the decision being made, such as a platform approval. Real icons help recognition, but a diagram covered in logos reads as a procurement list, and it distracts from the flows when the audience is deciding about outcomes rather than tools.

How do you keep a business view and a technical view from contradicting each other?

Build both from one model instead of two files. Collapsing groups turns a detailed engineering diagram into a small business view, so there is a single underlying structure and no second drawing to update when the platform changes. The failure mode to avoid is two independently drawn files, which diverge within a quarter and leave the audience unsure which one to believe.

What should be on the engineering version that is never on the business version?

Physical container names, job names and schedules on the edges, grain sentences on fact tables, history policy on dimensions, and the failure surface such as retries and reprocessing entry points. Those are what somebody needs while changing or repairing the platform.

Is it worth maintaining two diagrams?

It is worth maintaining one model with two views, not two diagrams. Two independently drawn files diverge within a quarter and then neither is trusted, whereas one canvas with collapsible groups gives both audiences their own level of detail from the same source. Publish them differently: the detailed view as a live embed that always renders the current version, the summary view exported for a deck.