Manual edits on a synced diagram: what holds, what moves, what to do instead

Before worrying about what a regeneration does, it helps to know how rarely one happens. A sync first checks whether the tracked ref moved, and stops if it did not. If it moved, it hashes the material that feeds the diagram and stops again if that hash is unchanged, which is the case for a README edit, a new test, a dependency bump, or a formatting pass.

So the common outcome of a daily sync on an active repository is that your canvas is not touched. Regeneration is reserved for changes that would actually alter the picture, which is the only time redrawing is worth the disruption.

Positions of nodes you moved. Every sync records the coordinates it wrote for each identified node. The next one compares the canvas against that record and treats anything more than 12 pixels away on either axis as hand-placed: it is pinned and restored to your coordinates after the new layout runs. Nodes you never touched stay free to be re-laid out, so an untouched diagram improves while a hand-arranged one holds still.

Identity and structure. Node identities come from the ids the generator assigned, recorded on the canvas, and on the Terraform path they are derived from resource addresses, which makes them stable by construction. On a regeneration the previous ids, labels, and zones are handed over with explicit instructions: keep what still exists, create ids only for genuinely new things, remove a node only when the source no longer contains it, and do not rename or re-split zones because a different arrangement occurred to you.

Identity itself comes from a sourceId recorded on each node when the canvas is written. On the Terraform path those ids are derived from resource addresses, so module.databricks plus azurerm_storage_account.this always produces the same id and a re-sync updates a node instead of replacing it. Elsewhere the ids are the generator's own, carried forward by the continuity block below.

Edit made by hand              On the next regeneration
  moved a node                   restored to your coordinates
  renamed a generated node       may be regenerated under its source name
  added a note or a shape        carried over, by instruction
  deleted a generated node       comes back if the source still declares it
  reworked the whole layout      kept for the nodes you moved

Continuity here is not a vague instruction to stay consistent. Before a regeneration, the canvas as it stands is described back to the generator: the zone names with their ids, then every identified node as id, label, type and zone, up to sixty of them, then a count of the ones it cannot identify. Those unidentified nodes are the ones you added by hand, and the block names them as such.

The rules that follow that listing are worth reading, because they say exactly what continuity promises.

The honest summary: positions and skipping are enforced in code, content continuity is enforced by grounding. A node you moved comes back by arithmetic. A node you added is kept because the generator was told to keep it, which is a strong steer and not a mechanical guarantee.

Zones: "Ingestion" (zone-ingestion), "Warehouse" (zone-warehouse)
Nodes (id | label | type | zone):
  node-orders-api | Orders API | service | Ingestion
  node-events-topic | orders.v2 | queue | Ingestion
  … and 41 more
Plus 3 node(s) added by hand on the canvas. Keep them: they are the reader's own work.

Continuity rules for this update (they outrank your instinct to recompose):
- Anything above that STILL EXISTS in the source keeps its id, its label, its type and its zone.
- Emit a NEW id only for something genuinely new in the source.
- Drop a node only when the source no longer contains it.
- Keep the zone set and the reading direction. Do not rename zones, re-split
  them, or switch arrangement because a different shape occurred to you.
- A reader has already learned this diagram. A small source change must read
  as a small diagram change.

Some diagrams are not really repository diagrams. A board-facing picture with narrative zones, a target architecture for next year, an incident retrospective drawing: those want to be stable, and a source of truth that keeps moving underneath them is a liability rather than a feature.

Three ways out, in increasing separation. Turn daily sync off for that diagram, which leaves the link in place for manual refreshes when you decide you want them. Unlink it, which keeps the project and its canvas and stops the syncing entirely. Or duplicate the project, keeping the synced original as the always-current base and the copy as the annotated artifact.

The fourth option is to stop annotating the diagram and annotate around it. Zone labels naming the domain, a paragraph of context above the live embed, and a note in the architecture.md all survive regeneration completely, because they are not on the canvas.

• Daily diagram sync, explained
• Repo to diagram: how repository sync works
• The diagram nobody maintains
• The Datadef canvas editor
• Repository sync documentation