Use Case Guide

Onboarding diagram: what a new engineer should see on day one

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

A new engineer spends the first fortnight rebuilding, in their head, a picture that already exists in four other heads. The onboarding diagram is the artefact that shortens that: one map of the system at the level a newcomer can hold, with the names they will hear in standup on it. It is also the document with the shortest useful life in the repository, which is why the interesting question is not what to draw but who keeps it true after the third refactor.

Try it free
6 min readFor platform teams onboarding engineers into an existing system

See it as a diagram

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

177/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

One diagram, not the wiki

Onboarding documentation usually fails by volume. Forty pages of accurate prose is not a worse artefact than one diagram, it is a slower one, and a new engineer reads it at the exact moment they have the least context to sort important from incidental. The diagram earns its place by being the thing a person can memorise in a morning.

The level to draw at is the level people speak at. If the team says the ingest service, the feature store, and the scoring API in conversation, those are the nodes. Anything the team never names out loud is detail, and detail belongs in the doc the newcomer reads in week three, not on the map they read in hour two.

Put a named owner on every zone. The single most useful thing an onboarding diagram gives a new engineer is not the topology, it is knowing who to ask about each part of it. That fact is also the one nobody writes down, because everyone in the room already knows it.

Two diagrams, because there are two audiences

Platform teams onboard two kinds of people, and one diagram cannot serve both. Application developers joining the platform need the developer-facing view: what they interact with, which golden paths exist, where their service ends and the platform begins. Engineers joining the platform team itself need the internal view: what the platform is made of, which control plane runs what, where the state lives.

Drawing both is cheap when they share a canvas grammar. Zones for boundaries, labelled edges for what actually crosses them, real vendor icons so the reader maps a box to a thing they can log into. Two projects, one for each audience, and the newcomer is handed the right one instead of the union of both.

The internal diagram is the one that should be grounded in the repository, because it is the one that changes most. Connect the platform repo read-only at your main branch and the picture regenerates from the source instead of from memory. See repository sync for what that reads and what it does not.

Why the onboarding diagram rots first

Onboarding docs go stale on a predictable schedule: they are written once, at high effort, by someone who then leaves the team, and the next person who notices they are wrong is the next new hire, who has no standing to say so. By the time the error is reported, three refactors have landed on top of it.

A synced diagram breaks that loop by removing the human step. The connection re-reads the branch about once a day, resolves the head commit, and stops there if it has not moved. If it has, it hashes what actually feeds the diagram, the selected file corpus, and skips generation when that hash is unchanged. A README fix, a test, a comment and a dependency bump all move the commit sha and none of them move the hash, so the picture does not churn, nodes you moved by hand keep the position you gave them, and the layout your team learned to read stays the layout.

This also changes who can maintain it. A new engineer who spots a wrong arrow in week one can fix it on the canvas without owning a documentation process, and the correction survives the next sync.

Make it the page they land on

Put the diagram in the onboarding README with a single markdown image line and it renders the current version for every future hire. See live embeds.

Getting it in front of the new hire

The diagram should be one click from wherever onboarding starts. If your checklist lives in Notion, embed it there. If it lives in the platform repo, embed it in the README. The embed is a permanent URL that renders the current diagram, so the onboarding page does not need an owner who remembers to re-export.

A new hire can be added as a viewer straight away and read the diagram and its versions. Editing is what needs a plan on both sides: a person without a paid plan or an active trial is a viewer in practice, and the server enforces that regardless of the role the dialog was told to grant. On a team workspace, the seat is what changes them from a reader into someone who can correct the map.

If your engineers work in Claude Code or Cursor, the Datadef MCP server lets them pull a diagram into the editor session and ask questions against it while they read the code it describes. See agents and MCP.

FAQ

How detailed should an onboarding architecture diagram be?

Draw at the level the team speaks at. If a component is named out loud in standup it belongs on the map; if it is never named, it is week-three detail. A useful rule of thumb is that a new engineer should be able to redraw the diagram from memory after one morning.

Should the onboarding diagram be different from the platform team diagram?

Yes, when you onboard both kinds of people. Application developers need the developer-facing view of what they interact with and which paths are supported. Engineers joining the platform team need the internal view of what the platform is built from. Two projects sharing one canvas grammar serves both better than one merged picture.

Who keeps the onboarding diagram up to date?

Nobody, if it is grounded in the repository. A read-only connection re-reads the branch about once a day and regenerates the diagram, and commits that change nothing structural do not redraw it. Manual corrections stay, because nodes moved by hand keep their position across syncs.

Can a new hire view the diagram before they have a paid seat?

Yes. Viewers can open the diagram and its version history. Editing is what requires an active plan on both sides: a person without a paid plan or trial is treated as a viewer even if invited as an editor, and this is enforced by the server rather than by the interface.

Can the onboarding diagram live in Notion or Confluence?

Yes. A single markdown image line pointing at the embed URL renders the current diagram inside the page, and it keeps rendering the diagram as the canvas changes rather than as it stood when the page was written. Readers need no account, and the same URL works in a README, a Confluence page or a docs site.