IcePanel Docs
Search
K

Diagramming

Diagrams are at the centre of IcePanel. Combined with the C4 model, you can effortlessly show how your system fits together at different levels of detail. Go from a high-level overview of your system to the apps and components that make it work. Add tags and flows to communicate different stories about your system. IcePanel's model-based philosophy allows you to create reusable objects across different diagrams, leading to greater consistency.
Diagrams in IcePanel are based on the C4 model

Diagram basics

Creating a diagram

The diagram hierarchy in IcePanel is based on the C4 model, with 3 levels of connected diagrams (instead of Level 4 diagrams, we allow you to link objects to reality). There are 2 ways to create diagrams.

On the landscape page

  1. 1.
    If your landscape is empty and contains no diagrams, click on the New context diagram button
  2. 2.
    If your landscape already contains diagrams, click on the New the button beside the Context diagrams label
Creating a diagram from the landscape page

In a diagram

  1. 1.
    Navigate to the top left and click on the Diagrams dropdown
  2. 2.
    Click on the New diagram button
Creating a new diagram from the diagram dropdown
Diagram groups are only available on Growth and Isolation plans.

Diagram details

The top-level navigation bar in a diagram contains metadata and wayfinding functionality.
Here you can:
  • View the version of the object and timeline
  • Freeze the landscape, domain, system, or app (Versioning)
  • See which diagram level you're in (Level 1, 2, or 3)
  • Go back to where you were previously
  • Navigate between different diagrams in a level
  • View and edit the name of the diagram
  • See who last edited the diagram
  • View the version of the diagram and create a draft (Draft current vs future state design)
  • View or edit the description of the diagram
Top-level navigation bar in a diagram

Creating new objects

Adding an object to a diagram creates it in the model. This means you can reuse the same objects across different diagrams or make a single edit (to its name, for example) to change it everywhere. There are 3 ways to add new objects to a diagram.

In the left toolbar

  1. 1.
    Navigate to the left toolbar and hover on the Add button. A list of object types will appear
  2. 2.
    Select the object type you want to add and place it in the diagram. You can also drag and drop
Creating a new object in the left-toolbar

In the diagram area

  1. 1.
    Double-click in the diagram area
  2. 2.
    Click on the object type you want to add
  3. 3.
    Name your object
Creating a new object in a diagram
Using keyboard shortcuts
  • Create a new system: Shift + S
  • Create a new actor: Shift + P
  • Create a new area: Shift + G
  • Create a new app: Shift + A
  • Create a new store: Shift + D
  • Create a new component: Shift + X
See all Hotkeys

Adding existing objects

There are 2 ways to add existing objects to a diagram.

In the left toolbar

  1. 1.
    Navigate to the left toolbar and click on the Existing objects button
  2. 2.
    Search for objects by name or toggle by domain
  3. 3.
    Click on the object you want to add to the diagram or drag and drop
Existing objects panel in a diagram

In the diagram area

  1. 1.
    Double-click in the diagram area
  2. 2.
    Search for the object by name or select the object from the dropdown list
Adding an existing object in a diagram

Editing object details

Click on an object to view/edit properties on the right-hand menu, such as:
  • Icon (for systems, apps, and components)
  • Object name
  • Object type
  • Status - Live, Future, Deprecated, Removed
  • Parent
  • Owners
  • Diagrams the object are in
  • Flows the object are in
  • Tags
  • Descriptions
  • Technology
  • Reality links
  • Editable permissions (only available on Growth and Isolation plans)
  • Connections to and from the object
  • History of changes to the object
Any changes you make will affect the model and across all diagrams the object is in.
Object details menu
There are 4 ways to navigate across diagrams:
  1. 1.
    Clicking on specific diagrams from the landscape page
  2. 2.
    Clicking the 🔎 icon at the top-right of an object in a diagram. A numeric indicator will show how many objects are nested within the object. If there are no nested objects, a blank diagram will be created at a lower level when you click on it
  3. 3.
    Clicking on the Level dropdown at the top of the navigation bar
  4. 4.
    From the diagrams dropdown on the top navigation bar
Navigating across diagrams

Connections

Adding connections

Connections are stored in the model as 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.
To connect model objects:
  1. 1.
    Use the + circular buttons on the edge of each object to drag a connection to another object
  2. 2.
    If an existing connection exists in the model, it'll appear in a dropdown over the connection
  3. 3.
    Name the connection to create a new one, or click on the New connection button
Blank connections are not added to your model until you give it a name.
Each object has 12 unique connection points, except for actors with 6. We recommend having connections sent and received from unique points instead of overlapping for legibility.
App object with connection points

Editing connections

Click on a connection to view/edit things such as:
  • Name
  • Sender
  • Receiver
  • Status - Live, Future, Deprecated, Removed
  • Direction - Outgoing (default), No direction, and Bidirectional
  • Line shape - Curved line (default), Straight line and Square edge line
  • Text position
  • Tags
  • Technology
Connection details menu

Using lower connections

Existing connections from lower levels in the C4 model can be reused at higher levels. These are called lower connections and will sync changes in the original 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 lower connections will also update, including the sender and receiver of the connection in all diagrams in which it is located and the flows that the connected objects are in.
Adding implied connections at Level 1

Showing relationships from another scope

Using the expand option, you can show apps inside a system talking directly to an app inside another system.
To do this:
  1. 1.
    Go to a Level 2 (app) or 3 (component) diagram
  2. 2.
    Add an external system
  3. 3.
    Select the Expand option in the object details menu
Using the expand option to connect apps in 2 different systems

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 see 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 connections belong in.
Changing a connection to another object

Diagram vs model changes

You can think of diagrams as a visual representation of a model. You can visualize the same model through different diagrams depending on what you want to communicate. When you update or delete your model objects, the changes will be made globally, wherever that object exists. This saves you time from manually going to each object and updating it.
Deleting objects using the delete key in a diagram does not remove them from your model. To permanently remove objects from your model, delete them from the object details menu or the Model objects tab (on the landscape page).

Diagram best practices

Here are some tips when creating diagrams:
  • Name all of your diagrams
  • Name all of your objects (including connections) clearly
  • Add icons to as many objects
  • Add display descriptions to each object
  • Create separate diagrams at the same level to reduce complexity
  • Use the right level of complexity at each level (Level 1 should have fewer objects than Level 2)
  • Use the same connection type in a diagram (avoid mixing curves and straight lines)
  • Only use bidirectional connections for open connections like websockets. Otherwise, show the request connection and use Flows to show the response
  • Avoid overlapping connections in a diagram for legibility

Continue your IcePanel journey 🚀

Flows
Show different use cases
Linking to reality
Connect objects to code