Use Case Guide

Client architecture documentation: the deliverable a consultancy hands over

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

Clients judge a data engagement by how confidently their own team can carry it on after the invoice. The architecture documentation is where that judgement happens: a diagram they recognise, a written description of what runs where, and access that outlives the consultants. The parts that decide whether it lands are unglamorous: what the deliverable contains, how much of it you can produce before repository access arrives, and how one client stays invisible to the rest of the practice.

Try it free
7 min readFor data consultancies documenting a client platform

See it as a diagram

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

169/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

What the deliverable has to contain

A defensible architecture deliverable has four parts. A current-state diagram at the level the client sponsor can follow. A written description naming the actual systems, not categories. An explicit list of what the assessment could not see, because a diagram that hides its blind spots is worse than no diagram. And a way for the client to open the whole thing next year without calling you.

That last part is the one most engagements get wrong. A picture pasted into a slide deck is dead the moment it lands in the client shared drive. A Datadef project can be switched to a link anyone can open: visitors pan, zoom, and go fullscreen without signing in, and the link never grants editing. The sponsor forwards it internally, the client architect opens it eighteen months later, and nobody has to find the original file.

Keep the diagram and the prose in the same place. When the repository is connected, the sync writes an architecture document alongside the diagram, so the written half is generated from the same reading of the code as the picture.

Drawing before you have repository access

Access on a consulting engagement arrives late, and the assessment interviews happen first. Start from the interviews: describe the platform in a sentence or two and get a first canvas with real vendor icons, so the client recognises Databricks, Data Factory, or BigQuery as their own rather than as grey rectangles. Correct it live in the next workshop, which is usually the fastest way to find out that the diagram everyone believed was wrong.

When access does arrive, connect the repository read-only and let the picture become grounded. Datadef reads GitHub, GitLab, or Azure DevOps at a branch or a tag. Public repositories need no token at all. Private ones take a scoped read-only token: a fine-grained GitHub token with Contents Read-only, a GitLab token with read_api, or an Azure DevOps token with Code Read. That list is short enough to put in the access request email, which is usually what gets the request approved.

What also helps is being able to say exactly what leaves the repository. A sync takes at most 40 files and 250KB in total, at most 30KB from any single file, chosen in a fixed priority order: infrastructure code first, then containers and orchestration, then data definitions, then API specs, then CI configuration, then dependency manifests, then README and architecture prose. Lockfiles, binaries, node_modules, vendor and .terraform never contribute. Under the architecture focus the per-class ceiling is 16 Terraform files against 3 dbt models, so a client warehouse with four hundred models sends three of them and the rest of the budget goes to the infrastructure the diagram is actually about.

One thing to check before promising a repo-grounded deliverable: self-hosted instances are not supported yet. A client on GitHub Enterprise Server, self-managed GitLab, or Azure DevOps Server keeps the interview-based diagram instead, which is still the deliverable, just not one that re-syncs. See how repository sync works for the full picture.

Keeping one client separate from the rest of the practice

A consultancy workspace holds several clients at once, and most of them would object to the others seeing their platform. A team workspace covers up to 5 seats under one subscription, and folders inside it can be restricted: in a restricted folder, being a team member is no longer enough to see the projects inside, only the people added to the folder can. Team owners and admins keep access, as does anyone invited to a specific project directly.

That maps to how engagements are actually staffed. One restricted folder per client, the two consultants on the account added to it, the partner keeping visibility through the owner role. Invitations expire after 14 days if nobody accepts, so a contractor who rolled off does not sit in the workspace as a pending seat.

Seats are counted as members plus pending invitations against the cap of 5. On a practice that rotates people between accounts, revoke the invitation of anyone who left before inviting the next person, or the invite is refused.

The NDA folder

A restricted folder is the right home for a client whose architecture is under NDA. Restriction narrows the team-wide grant and nothing else, so the project still behaves like any other project for the people inside it. See teams and folders.

Handing it over at the end

For the written report, export the canvas as PNG or JPEG and place it in the document like any other figure. For anything the client will read repeatedly, give them the live version instead: one markdown image line puts the current diagram into their Confluence page, their Notion space, or the README of the repository you built, and it keeps rendering the diagram as it stands rather than as it stood on delivery day.

When the engagement closes, unlinking the repository leaves the project intact with its content, so the client keeps the diagram without the consultancy keeping a read token on their code. If the deliverable was made public for distribution, remember that switching it back to invite-only stops the link and every embed of it immediately, which is the behaviour you want on the day the NDA period ends.

## Platform architecture

![Client data platform](https://datadef.io/api/embed/your-project-slug)

_Live diagram, regenerated from the repository. Not a screenshot._

FAQ

Can the client open the architecture diagram without an account?

Yes. The project owner can switch a project to a link anyone can open. Visitors get a view-only page with pan, zoom, and fullscreen, and no sign-in is required. A public link never grants editing, so forwarding it inside the client organisation cannot change the diagram.

What if the client will not give us repository access during the assessment?

Draw from the assessment interviews instead. You describe the platform in plain language and correct the canvas in the next workshop. Repository grounding is an upgrade you can add later by connecting the repo read-only at a branch or tag, not a prerequisite for producing the deliverable.

How do we keep one client invisible to the rest of the practice?

Put the engagement in a restricted folder inside the team workspace. Only people explicitly added to that folder can see the projects inside it, while team owners and admins retain access. Personal folders are purely organisational; restriction is a property of team folders.

What image formats can we put in the written report?

PNG and JPEG. Export both from the canvas and place them in the report like any other figure. For documents the client will re-read, an embed of the live diagram is a better choice than a pasted image, because it does not go stale.

What happens to the diagram when the engagement ends?

Unlink the repository and the project survives with its content, so the client keeps the documentation without you keeping a read token on their code. If the project was shared by public link, switching it back to invite-only stops that link and any embed of it immediately.