Skip to main content

Modeling tool

Modeling tool​

A click on the Label of a diagram will open it in the Modeling tool. This tool is designed to help software architects create, manage and refine architectural diagrams with ease.

In the top right corner of the page, there is an overflow menu. Here, you have the following options concerning the diagram as a whole:

  • Show details: Display the diagram details in the modeling tool
  • Share diagram: This opens a dialog where you can copy the diagram's URL or share it directly via email.
  • Clone diagram: Creates an exact copy of your diagram (see Clone a diagram)
  • Export as PNG: Export your diagram as an image in the PNG file format
  • Clean up diagram: Clean up corrupted and unused data from the diagram (such as one-sided connections, non-existent parents or unused relationships), which can be accidentially produced by direct git interactions
  • Delete diagram: Delete the whole diagram. You will need to confirm the action before the diagram is permanently deleted.

The modeling canvas​

The canvas is the central workspace of the modeling tool. It provides an interactive, drag-and-drop environment to easily add, position, and connect model elements such as systems, containers, components and actors.

You can click anywhere and drag the canvas in order to navigate through the diagram.

In the top left corner, you find capabilities to

  • Toggle selection mode
    • When selection mode is on, you can select several cards at once to reposition them on the canvas. Expanded systems/containers can be moved as a whole by clicking and dragging the icon appearing in the top right corner of their frame. The selected group of elements as a whole can also be copied , inserted and deleted via common keyboard shortcuts.
    • In normal mode, you can move freely around on the canvas by click and drag.
  • Toggle the interactivity of the diagram, e.g. for presentation or overview purposes
  • Auto layout with further options to adjust your view
  • Undo and Redo
  • Configure cards: Customize the title, text, additional values and tags of the model elements in this diagram. Custom fields are available as well.

In the bottom left corner, a mini map visualizes which part of the diagram is being displayed on the canvas at the moment. You can also use this mini map to move around the canvas and adjust the zoom level. The Fit view functionality sets the zoom level and canvas to the optimal settings to view as much of your diagram as possible. You can also Hide the mini map here.

Adding model elements​

In the top right corner of the canvas, you can find a (+) button with which new elements can be added to the canvas.

  • New elements can be found at the top of the menu. You can directly enter a label for the element and add it to the canvas; alternatively it is also possible to just drag-and-drop an element from the list into the canvas and name it afterwards.
  • Available elements lists all model elements that already exist in the project (see Model elements) and are available to be used in the diagram. They are sorted by type (Actors, Systems, Containers, Components).

Editing model elements​

With one click on a model element card, you can open its details; here you can view and edit the same information that is also provided in the Model elements overview:

  • Details: Master data of the model element (see also Create a model element); all writable fields are editable here as well.
  • Usages: Displays where the model element is already in use. This can be Diagrams and/or Groups within diagrams to which the element has been added, as well as Systems (for Containers) or Containers (for Components), if the element is already part of a system/container.
  • Relationships: This tab comprises all Incoming and Outgoing relationships to other model elements of the project. In a diagram, these relationships are visualized as arrows between model element cards. Clicking on one of the elements in this section highlights the corresponding element in the canvas as well.
  • Loop: Here, you can find links and connections to other parts of the project.

All changes that are done here are automatically reflected in the Model elements overview, and vice versa.

Managing model elements​

When clicking on a model element, a menu with different options is displayed above the element, depending on its type. Alternatively, you can also right-click on a model element to access the same actions.

  • Copy: Copy a model element, also via CRTL+C
  • Cut: Cut a model element, also via CRTL+X
  • Paste: Paste a model element, also via CRTL+V
  • Clone: Clone a model element. This creates a new model element with the same data but a new identifier.
  • Drill up or Drill down: If there are diagrams for levels above or below this model element, you can directly drill up/down from here.
  • Create diagram: Create a new diagram of the next level for this model element.
  • Normal view mode and Expanded view mode: Changes the view of a system or container between normal view and expanded view to add elements inside (read more about this here). Please be aware that only one card can be displayed in expanded view at the same time if you put the same system or container into one diagram several times.
  • Open spotlight: Opens the spotlight of this model element in an overlay over the canvas (close via the X icon or ESC)
  • Create new project: For containers, a new implementation project can directly be created from the model element
  • Detach from group/system/container: Detaches this model element from the parent or group it is currently placed in, so that it can be moved out of the parent model element or group.
  • Add available relationships: Adds all available relationships of the model element that are not set on the diagram.
  • Remove from diagram: Removes the model element from this particular diagram. You can still find it in the available model elements. Can also be achieved by using DEL.
  • Delete from project: Deletes the model element from the project. You will need to confirm the action before the selected model element is permanently deleted.

Removing and deleting model elements​

In the model element details, you can also access the capabilities to Remove the model element from the diagram and Delete the model element from the project altogether in the overflow menu of the details header.

⚠warning

If you delete a model element, child model elements inside are not going to be affected. You will need to confirm the action before the selected model element is permanently deleted.

All changes that are done here are automatically reflected in the Model elements overview, and vice versa.

Connecting model elements (Relationships)​

Each model element card has two nodes for adding relationships. Just click on the bottom node and drag the cursor to the top node of the model element you want to connect it to. The Incoming and Outcoming endpoints are immediately reflected within the Relationships tab of the model elements details as well. You can specify the type of relationship between the two elements by clicking on the relationship and entering a label in the sidebar.

Relationships can easily be removed by selecting them and using the DEL key on your keyboard. As long as a relationship between two elements is used at least once in the project, it will always be displayed in the Relationships tab of the corresponding elements.

❗️info

If you remove a relationship between two model elements, it does not get deleted as a whole, but will be re-added automatically if you connect the two elements again.

Creating additional levels of a diagram​

A system model element can comprise one or several containers, and a container can comprise one or several components. In order to correctly reflect these connections, a new corresponding diagram must be created.

If you want to further model a system, right-click on the system card and select Create diagram in order to create a new Container diagram (Level 2) for this system. The new diagram level will automatically be displayed. The system card will become larger and can be adjusted in size; containers can then just be dragged an dropped into the system. The same procedure applies to containers and their components (Level 3 - Component diagram).

If there already are one or several corresponding diagrams (indicated by an arrow in the bottom right corner of the model element card), you can drill down into the next level by right-clicking on the card and selecting Drill down. You can then select the diagram to which you want to drill down. To drill back up to the former diagram click on the arrow icon in the top left corner of the canvas header, next to the title.

❗️info

It is possible to have several systems in a container diagram (and several containers in a component diagram) and to expand each of them them to add further model elements inside. It is, however, recommended to work according to C4 Modeling principles and use several diagrams to model specific aspects of your system architecture.

Managing model elements within other model elements​

If you add a system to a container diagram, or a container to a component diagram, and want to add elements into these parts, you first have to expand the system/container. To do this, right-click on the element you want to expand and select Expanded view mode. The card then becomes bigger and items can be moved inside. You can go back to the simple card view of a system/container by right-clicking again and selecting Normal view mode in the menu.

As soon as a model element is inside a parent model element (system, container, or group), it cannot be moved outside of the parent element anymore. If you want to move an element out of a parent element, you first need to detach it. Right-click on the element you want to move and select Detach from group/system/container. The element can then be moved outside again.

Groups​

Groups are a way to visually organize and categorize model elements within a diagram, e.g. for domains or infrastructure. In the modeling tool, you can create groups to group systems and actors (level 1 diagrams), as well as containers (level 2 diagrams), and components (level 3 diagrams). They can also be placed inside systems or containers.

It is not possible to connect groups to other model elements via relationships.

Creating a service project for a container​

For container model elements, you can also directly create a service project for subsequent implementation. Create new project can be accessed via right click on the container in the canvas, as well as from the overflow menu of a container's details view.