Diagramming - The visual scenarios

Whether you've pre-defined your model or are defining it as you go in the diagram view, diagramming is at the centre of IcePanel. You can effortlessly show how your System fits together by using the different C4 model diagram levels, depending on your story and the audience you are talking to.

Check out Modelling for more detail on the C4 model.

A visual representation of zooming in on model objects and the level they belong at.

Diagram levels

Level 1 - Context diagram

This is your starting point!

Starting at the highest level of detail, you can add Systems, Actors and Areas from the left hand tool bar by clicking on or dragging onto the canvas before connecting them up. This is done by hovering on edges to show connection points, to show the relationship between objects. View Connections for more detail on this.

These diagrams are used to explain the highest level of detail about the System you are designing and the overall ecosystem it sits within.

Remember that this is for anyone, to understand the general use of your System - simplicity is key.

A context diagram example.

Level 2 - System diagram

This is known as a container diagram in C4 - we chose to call them App diagrams to avoid the Docker confusion. (sorry Simon)

Once you have your system(s) added, you can zoom into them using the + 🔍 symbol and start adding some more detail. Here you can show the deployable applications and stores that makes your Component work, by adding Services / Apps and Databases / Stores from the left hand tool bar. You can bring in your Actors and external systems to show the communication or messages going to / from them also.

There is more detail added at this level, but remember to focus on the reason why the diagram exists, making it easy for your intended audience to pick up and understand.

An App diagram example

Level 3 - Component diagram

You can now zoom in on your Apps using the + 🔍 symbol to add lower levels of detail about how each individual App works. Add Components within each App and connect them up to show App building blocks of that App and the functionality. You can also bring in apps from the same system, actors and external systems to show dependencies outside of that App.

This is the lowest level of detail inside IcePanel and is intended for more technical audiences, so make sure connections are labelled and everything is explained, so you don't have to be there to answer every question others have when you share.

A Component diagram example

Connections

The right hand panel showing an unnamed Connection with an existing Connection for the 2 connected objects and Implied connections available.

Connections are stored in the model as actual relationships. This means you can reuse those connections in other diagrams between the same object, keeping changes in sync and even allowing you to use connections from lower levels at higher levels as "Implied" connections.

Adding new connections

To connect your model objects, use the + circular buttons on the edge of each object to drag a connection to another object. A blank connection will be created and is only used for visuals for that diagram. Blank connections are not added to your model until you give it a name.

You can connect from 1 connection point on each edge of the object to begin with, but once that has been used, you can also connect from and to 2 extra positions - totalling 3 positions on each edge.

Adding a connection between an actor and a system

Naming new connections

Naming a connection can be done in 2 places.

• On the connection itself with the "+ New connection" button placed in the centre of the line
• In the field at the top of the right-hand panel when a connection is selected.

Using existing connections

You can select existing connections from the right-hand panel, in the "Existing direct connections" section, which carries over the documentation added to the connection previously.

These connections will show if a relationship has been created between those 2 objects previously.

Adding an existing connection between an Actor and System.

Using implied connections that exist lower down

You can use existing connections from lower levels of detail, when adding a connection at higher levels of detail. These are called Implied connections, and will sync the changes of the original direct connection.

These connections will show if a relationship has been created between objects inside (child objects) of those 2 objects previously.

When the original connection is updated, the Implied connections will also update, including the sender and receiver of the connection in all diagrams that it has been drawn in, and flows that the connected objects are in.

Reusing an implied connection at a higher level

Connection design styles

Connection styles can be edited once it has been given a name.

This includes:

• Connection direction - No direction, Outgoing (default) and Bidirectional
• Line shape - Curved line (default), Straight line and Square edge line
• Label position - Start, Middle (default) and End

Connection design options of a named connection

Change connection position on same object

To change the position of a connection start or end on the same object, click and drag the start or end of a connection to a different connection point shown by the dots around that object.

Change connection to another object

To change the connection in the model to another object, click and drag the start or end of the connection to the other object you want to use that connection on.

You will be shown a modal to select either "New connection" or "Change connection in model":

• New connection: This creates a duplicate new connection for that change with the same name (it does not copy over documentation).
• Change connection in model: This will change the connection in the model and sync with your diagrams that the old and new connection belong in.

Connection model change modal

Change connection name

To change the connection name, you first have to reset it back to a blank connection. Simply editing the name of a connection will change the connection name everywhere it existed.

There are 2 ways to create a new connection:

• Change connection button: Click the "Change connection" icon at the right hand side of the connection name to reset the current drawn connection.
• Draw a new connection: you could also simply draw the connection again and create a new connection.

Change connection button hover state on a connection called "New connection".

Same connection used in other diagrams

You can quickly view the other diagrams that a connection exists in, by selecting the "Other diagrams" drop down and clicking the link to view each diagram.

Other diagrams dropdown open showing the other diagrams the "New connection" connection exists in.

Multiple diagrams at the same level

You can create as many diagrams at each level as you want by clicking the + button in the secondary navigation.

You can either duplicate the diagram you're currently viewing, or create a blank diagram.

The first diagram is considered the "pinned" diagram or entry diagram. This is the diagram you land on when you zoom in from the level above using the +🔍 icon.

You may wish to use this to show different flows, use cases or maybe split business and technical logic. This also helps you split out larger models into separate, smaller diagrams to be more specific when you want to show a particular person or audience, keeping focus on the conversation you're having.

Secondary navigation showing the Online Boutique App diagrams.

Our recommendation is to use diagram tabs to target specific audiences: Technical, Business, Product and/or specific user scenarios.

See our flows feature for more on showing scenarios and message sequences.

Making changes in diagrams

Each diagram is it's own, but when you update or delete your model objects, the changes will be made globally, where ever that object exists. This saves you having to go and hunt down the objects to make the changes each time, making maintenance much easier.

This includes:

• Model object name change
• Object documentation change
• Icon change
• Connection name change
• Named connection to/from changes
• Perspective tags adding or removing
• GitHub link updates

Deleting objects from a diagram does not remove it from your model, only that current view. To remove objects from your model completely, either delete from the Model view, or the Model objects folder in the left hand toolbar.

Showing relationships from another scope

You can show apps inside one System talking directly to an App inside another System using the expand and collapse option.

You can do this from an App diagram and Component diagram by simply adding an external System to your diagram and selecting the "Expand" option. This is found to theright of the object name (if applicable). This adds a new section to your "Model objects" folder called "Other contexts", which allows you to add in objects that live within.

Objects from other contexts being added and expanded in an App diagram