Before any sync cycle begins, the model is validated using model.Validate(). If validation errors are found (e.g., invalid view include/exclude patterns, dangling references), sync aborts with an error message listing all validation failures. This prevents silent data loss from typos such as a trailing dot in an element ID ("customer.") which would otherwise silently remove elements from draw.io (#176).

Every element in the JSON model has a unique key (variable name) that serves as its ID. Nested elements use dot notation: webshop.api.auth.

In draw.io, the ID is stored in two places for reliability:

When views are used, cell IDs are scoped to ensure file-wide uniqueness: <viewID>--<elementID> (e.g., context—​customer). The bausteinsicht_id attribute always stores the un-scoped element ID.

Connector cells use a derived ID: rel-<from>-<to>-<index> where <index> is the 0-based position of the relationship in the model’s relationship array. The index disambiguates multiple relationships between the same element pair (#142).

When multiple relationships exist between the same pair (e.g., customer → webshop.api at indices 0 and 3), each gets a distinct connector ID:

During reverse sync, elements are matched in this order:

Triggered when the JSON model changes.

Triggered when the draw.io file changes.

New elements use grouped text sub-cells instead of a single HTML label. The parent element has label="" and three child <mxCell> elements for title, technology, and description. Each sub-cell has independent font size, color, weight, and positioning — matching PlantUML-level typography quality.

Sub-cell rules:

During reverse sync, ReadElementFields extracts values from sub-cells first. If no sub-cells are found, it falls back to parsing the HTML label (backward compatibility).

Older draw.io files may use a single HTML label attribute instead of sub-cells. The HTML label parser (ParseLabel) supports these formats:

Legacy color codes (#666666 for technology, #999999 for description) are also recognized for backward compatibility.

Children of the scope element (identified by dot-notation prefix, e.g., shop.api is a child of shop) are parented to the scope boundary cell. Their parent attribute on <mxCell> is set to the scoped cell ID of the boundary, so they appear visually inside the swimlane. Child coordinates are relative to the boundary’s top-left.

On any view page where the element appears, the link attribute is set to data:page/id,view-<viewID>. Clicking the element in draw.io navigates to its detail view (#198).

Detail views (views with a scope) get a back-navigation button that links to the parent view. The parent view is identified as any view whose resolved element set includes the scope element.

The button is an <object> with:

Back-navigation buttons are excluded from reverse sync element import (#205).

True self-loops (where from == to in the model) are rendered as connectors. However, when lifting causes both endpoints to collapse to the same element (e.g., shop.api → shop.db lifted to shop → shop), the resulting self-reference is skipped because it does not represent a meaningful relationship at the view’s abstraction level (#111, #212).

Relationships are processed in two passes to ensure correct deduplication (#197):

This ensures that when a direct relationship (e.g., api→db) and a lifted relationship (e.g., api.catalog→db lifted to api→db) map to the same pair, only one connector is created with the direct relationship’s label (#142, #197).

When generating a view that includes a container element and its children:

When detecting containment from draw.io:

A .bausteinsicht-sync file stores the state after each successful sync:

With the last-sync state, changes are detected as:

For the initial version, conflicts produce warnings:

In v1, the model value wins on conflict. This is the safer default since the JSON model is the declared source of truth for structure.

For simple field value changes (title, description, technology), PatchSave locates the target value in the raw JSONC text by walking the JSON path and replaces only the value bytes. The rest of the document — including // single-line comments, /* */ block comments, whitespace, and key ordering — is preserved.

For structural changes (new elements, new relationships), InsertObjectEntry and AppendArrayEntry are used to insert new JSON entries before the closing } or ] of the target container, preserving surrounding comments and detecting indentation from context.

When structural changes cannot be applied via patching (e.g., element deletion), a full Save is used which re-serializes the model and does not preserve comments.

The bausteinsicht_template attribute identifies which element kind this template applies to. The element style, dimensions, and sub-cell styles (font size, color, position) are all copied to new elements of that kind.

Relationship connectors also use template styles. The connector template is identified by bausteinsicht_template="relationship" on the <mxCell>:

The same element ID may appear in multiple <diagram> pages. Each page has its own <object> with independent position and a scoped cell ID (<viewID>--<elementID>). Changes to metadata (title, description) in one view propagate to all views during sync.

If a connector’s source or target references an element not present on the current page, the connector is removed with a warning.

A view with no matching elements generates a <diagram> with only the base cells and a text note: "No elements match this view’s include criteria."