Repository Sync Guide

Daily diagram sync explained: two checks before anything is redrawn

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

Automatic regeneration sounds simple until it runs against a real repository, where most commits change nothing a diagram would show. Redrawing on every push produces churn, noise, and a picture that shifts under people who were reading it. The interesting part of a sync is therefore not the drawing, it is the two checks that usually decide not to draw.

Try it free
6 min readFor teams who want the diagram current without a redraw on every merge

See it as a diagram

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

134/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

Check one: has the ref moved

A sweep runs every hour and picks up the linked diagrams whose last sync is more than twenty-three hours old, oldest first, ten per pass and one at a time so generation load stays flat. Twenty-three rather than twenty-four is deliberate: a diagram synced at 04:10 yesterday is due again at the 04:00 tick today, instead of slipping an hour later every day until it drifts across the working day. A Postgres advisory lock around the selection means that during a blue-green overlap only one instance claims the queue.

Each run starts the same way: resolve the head commit of the tracked branch or tag.

If that commit matches the one the diagram already reflects, the sync stops there. Nothing is fetched, nothing is generated, and the link simply records that it looked. For a repository that ships a few times a week, that is most of the runs.

Manual refreshes take exactly the same path, which is why hitting refresh on an untouched repository answers in a couple of seconds with the commit it is already at, rather than spending minutes reproducing the same picture.

Check two: did anything structural change

A moved commit is not the same as changed architecture. Somebody fixed a typo in the README, added a test, reformatted a file, bumped a comment. The sha moved, the system did not.

So the second check hashes what actually feeds the diagram: the parsed draw plan for a Terraform repository, or the assembled corpus of selected files otherwise. That hash is the structure fingerprint, a SHA-256 kept as its first 32 hex characters. When it matches the previous one, generation is skipped entirely, at zero cost, and the diagram people have already read stays byte for byte what it was.

This is the check that makes daily sync usable rather than annoying. Without it, every commit is a redraw, every redraw is a slightly different composition, and within a week nobody trusts that the diagram they are looking at is the one they looked at yesterday.

sync
 ├─ resolve head of tracked ref
 │    same commit as last sync?  ──▶ stop, nothing changed
 ├─ read the corpus (or parse the .tf files)
 │    same structure fingerprint? ──▶ stop, nothing structural changed
 └─ regenerate: diagram + architecture.md
      previous ids, labels and zones handed over for reuse
      hand-moved nodes put back where their owner left them

When it does regenerate

A real structural change produces a real regeneration, and the goal there is a small diff rather than a new drawing. The previous diagram ids, labels, and zones, up to sixty nodes of them, are handed to the generator with an instruction to keep everything that still exists, emit a new id only for something genuinely new, and drop a node only when the source no longer contains it. Zone names and reading direction are held steady on purpose, because a reader has already learned this picture. That block is added only when a diagram is being updated: a first generation has nothing to be continuous with.

Positions are handled separately, and by arithmetic rather than by instruction. Every sync records the coordinates it wrote for each identified node. The next one measures the canvas against that record, and anything more than 12 pixels away counts as hand-placed: it is pinned and restored after the layout pass, while nodes still sitting where layout left them stay free to move. An untouched diagram can therefore be re-laid out cleanly while a hand-arranged one holds its shape.

The architecture.md regenerates in the same pass, from the same read, so the doc and the diagram cannot disagree about what exists. Both land on the project, and any live embed of that diagram picks up the new version with no file to re-export.

The controls you have over it

Daily sync is on by default and can be turned off per diagram, which is the right move for a canvas you intend to hand-tune. A manual refresh is always available from the repositories page, and from an agent through the repo tools described in refresh a repo diagram from an agent.

Two operational details are worth knowing. A sync that has shown as running for more than ten minutes is treated as stale and can be claimed again, so a process that died mid-run does not leave a link stuck forever. And background syncs run while the connection owner is on a paid plan; if a plan lapses the scheduled runs stop without writing anything, and the diagrams, their content, and their history stay exactly as they are.

A failed sync never damages the diagram

A re-sync streams into a canvas that already holds a good diagram and may be serving public embeds, so the canvas is snapshotted before the first partial write and restored if generation dies mid-stream. The error is shown next to the link; fix the cause, refresh, and the picture picks up from there. See the repository sync documentation for the status list.

FAQ

How often does a linked diagram regenerate?

A sweep runs hourly and picks up diagrams whose last sync is more than twenty-three hours old, so each linked diagram is checked about once a day. Being checked is not the same as being redrawn: most checks end at the head commit comparison.

Does every commit redraw the diagram?

No. Two checks run first. If the tracked ref has not moved, the sync stops immediately. If it has moved, the material feeding the diagram is hashed, and an unchanged hash means the change was cosmetic, so generation is skipped and the existing diagram is untouched.

What is a structure fingerprint?

A hash of what actually feeds the drawing: the parsed model for a Terraform repository, or the assembled corpus of selected files otherwise. A README edit, a new test, or a formatting pass moves the commit sha but not the fingerprint, so nothing is regenerated.

Will a regenerated diagram look completely different?

It should not. The previous ids, labels, and zones are handed to the generator with instructions to reuse everything that still exists and to emit new ids only for genuinely new things. Zone names and reading direction are held steady, so a small source change reads as a small diagram change.

Can daily sync be turned off for one diagram?

Yes, per diagram rather than per connection, so one repository can have a living diagram on the default branch and a hand-tuned one that only moves when you ask. Turning it off leaves the link in place, so a manual refresh from the repositories page or from an agent still works whenever you want the picture brought forward.

What happens to a sync that crashes halfway?

A link showing as running for more than ten minutes is considered stale, and the next hourly sweep or a manual refresh can claim it again. The canvas is snapshotted before the first partial write of a regeneration, so a generation that dies halfway is rolled back to the last good diagram rather than leaving a half-drawn preview in place of real content.