Editing Model Diagrams

Author the DSL

• Give every view a concrete purpose in its description.
• Use variables or stable element paths for references; do not select elements by incidental rendered text.
• Preserve stable view keys and output filenames used by documentation or publishing. When intentionally removing a key, update references and remove its stale generated output because regeneration does not prove stale files disappeared.
• Use AddDefault, Add, and Remove deliberately. Avoid AddAll when it obscures the view's question.
• SelectRelationships is available only in a SystemLandscapeView. In other view types, curate membership and use Unlink for relationships that do not answer the view's question.
• Unlink hides a real source-model relationship from one view; it does not mean the relationship is absent. Never unlink solely to improve layout.
• Before every Unlink, ask whether a reader seeing both endpoints without the edge could reasonably infer that no relationship exists. If so, keep and arrange the edge, remove an out-of-scope endpoint, or split the view.
• A narrowly titled dynamic flow may omit relationships that are outside that exact runtime interaction. Make the scope explicit in the title and description, and ensure another purposeful view or authoritative documentation communicates any omitted relationship that matters to system understanding.
• Main and overview views must retain the key architecturally significant relationships among their visible elements. Do not make an overview look simpler by disconnecting services that materially depend on one another.
• NoRelationship removes every relationship to and from that element after view finalization, including explicitly linked relationships. Use it only when one element is intentionally isolated within an otherwise meaningful view, not to turn the whole view into a listing or as a general edge filter.
• In a DynamicView, Link(source, destination, description) selects an existing source-model relationship. The description must exactly match the canonical relationship description; it is not a display-label override.
• Linked dynamic-view elements may also render other model relationships among those elements. Compare the rendered edge count with the intended links and use Unlink for every incidental relationship.
• Supply the exact canonical description to Unlink, even when only one relationship exists between the source and destination.
• Describe relationships with domain actions such as "Publishes alarm state" or "Retrieves schedules", not vague labels such as "Uses".
• Keep relationship direction consistent with the runtime call, event, or data flow.
• Coalesce duplicate relationships only when one label truthfully represents them.
• Do not weaken or shorten canonical element metadata merely to make a crowded diagram fit. Prefer a smaller view or a layout/rendering correction.
• Use AutoLayout as the default complete placement. It measures rendered content, places nodes, boundaries, routes, and labels together, and rejects invalid geometry instead of saving a partial result.
• Treat an mdl svg geometry failure as a real model, view-scope, saved-layout, or MDL defect. Do not work around it by unlinking relationships, shortening truthful text, retrying with guessed spacing, or accepting a partly rendered file.
• Always inspect every rendered view visually. Compilation, successful rendering, and non-overlapping geometry are not evidence that the view communicates well.
• Use saved coordinates from the MDL visual editor only for intentional refinement. A manual layout must contain every current element, complete relationship routes, and placed labels; stale or partial saved geometry is invalid.

Regenerate and inspect

Render all affected views from the repository root, using the repository's pinned go tool mdl invocation when available:

mdl svg <model-package> -all -dir <output-directory>
# or: go tool mdl svg <model-package> -all -dir <output-directory>

For interactive layout refinement:

mdl serve <model-package> -dir <output-directory>

Arrange with the MDL visual editor

Start with AutoLayout, then visually review every view in the generated set. Keep the automatic result when its hierarchy, spacing, labels, and edge routing communicate the view's question clearly. Use the editor only when deliberate placement would improve that communication. When a rendered view has excessive whitespace, weak visual hierarchy, or avoidable edge crossings:

1. Confirm the view contains only relationships that answer its architectural question. Do not unlink a real relationship merely because its label or route is difficult to place. If too many in-scope relationships remain, split the question before positioning. Omit an incidental relationship only when the title and description make that scope clear and another purposeful view or authoritative documentation preserves the relevant fact.
2. Run mdl serve for the model package and output directory. If DSL changes while the editor is running, verify the displayed node and edge counts changed; restart mdl serve when it still shows the previously compiled model.
3. Select the affected view in the editor.
4. Arrange nodes, relationship labels, and boundaries so the primary architectural flow is apparent before reading every label.
5. Keep every boundary truthful while moving elements: only owned descendants may sit inside it, and sibling or external elements must remain outside.
6. Reset or reposition stale edge bend points and labels after moving nodes or changing membership. Saved routes from an earlier layout must not leave lines outside boundaries, unnecessary detours, or detached labels. If MDL rejects a stale or incomplete saved layout, regenerate that whole affected view or deliberately migrate every element and route together. Never mix old manual positions with newly guessed automatic values.
7. Save through the MDL editor so it records supported layout coordinates. Do not hand-edit generated SVG or JSON layout data.
8. Confirm the expected SVG's timestamp or content changed, wait for the write to finish, then reload the view from disk. Verify node coordinates and edge vertices survived before accepting the layout.
9. Reopen the persisted SVG at fitted viewport scale and verify the saved nodes, labels, arrows, and boundary titles.

For MDL renderer or layout changes, render the full repository view set at least three times and compare the SVG files byte for byte. Also run independent model packages concurrently. Any changed bytes between identical runs, port collision, timeout, partial file, or cross-view result is a tool defect.

Always review the main view in the editor and arrange it deliberately whenever that improves the whole-system summary. Review every secondary view at fitted viewport scale and arrange it as needed. Do not use manual positioning to compensate for excessive scope or an incorrect model; split or correct the view first.

After rendering, verify:

• Every expected element appears once.
• Across the published view set, every architecturally relevant owned service appears in at least one purposeful view or has an explicit documented reason to remain model-only.
• The main view represents every major subsystem and capability, even when detailed services are delegated to secondary views.
• Rendered node, edge, and boundary counts match the view's stated scope.
• Every Unlink has been reviewed against the source relationship, the view's stated scope, and the inference a reader may draw from its omission.
• The C4 abstraction level is consistent.
• All boundaries satisfy the ownership and non-overlap rules.
• External elements are outside internal boundaries.
• Relationship direction and labels are readable.
• Nodes, labels, arrows, and boundary titles do not overlap.
• Text stays inside its node or boundary.
• The complete structure is visible at common viewport sizes. Labels in an honestly dense overview may require zoom, but focused secondary views must make its major flows readable without hiding real relationships.
• Generated files match the DSL and are included when the repository publishes rendered artifacts.

Run the repository's architecture-drift checks, tests, and formatting commands after changing Go DSL.