editing-model-diagrams

Editing Model diagrams

Produce diagrams whose source model is architecturally true and whose rendered views communicate that model without ambiguous ownership.

Prioritize truth, readability, then polish

Use this order when design goals conflict:

1. Represent the real ownership, dependencies, directions, and runtime behavior.
2. Make that reality readable through the right abstraction level, focused views, deliberate layout, and clear labels.
3. Improve visual balance and polish without changing or hiding architectural meaning.

Never omit, reverse, reparent, or relabel architecture merely to make a diagram look cleaner. If a truthful view is unreadable, reduce its question, remove out-of-scope elements, or split it into additional truthful views while keeping the main view representative of the whole system.

Workflow

1. Read the model definitions, the affected view, and imported model packages.
2. State the one question the view answers and the expected elements, relationships, and boundaries.
3. Identify the owner of every element and the source-model relationship for every intended edge.
4. Choose the C4 view level that answers the question.
5. Preserve published view keys unless the requested change intentionally renames or removes an output.
6. Edit Model DSL source. Do not edit generated SVG or JSON output directly.
7. Regenerate every affected view.
8. Inspect the rendered diagram, not only the compiling DSL.

Preserve ownership

• A SoftwareSystem owns the Container elements declared inside it.
• A Container owns the Component elements declared inside it.
• Add, AddDefault, AddAll, and imported packages change view membership; they do not change element ownership.
• A deployment node may contain infrastructure nodes, child deployment nodes, and container instances. A container instance represents deployment of its referenced container; it does not transfer software ownership.
• Do not redefine or reparent an element to make a layout easier. Correct the model first, then select and arrange the view.
• A view cannot create a relationship absent from the source model. Do not invent or reverse an edge to complete a desired narrative; report or correct the model contract when evidence supports that change.
• When a repository inventory reports a missing service or element, verify its ownership and typed callers before adding it. Model the real container and relationships; do not add a name-only placeholder merely to satisfy a check.