IcePanel Docs
Search
⌃K

Getting started

Create your first IcePanel model

The basics

IcePanel is an interactive modelling and diagramming tool that uses the C4 model to help you communicate your team's system architectures in a structured way. It helps to explain how things work to your many audiences through an abstraction-first approach, overlaying details when needed.
With the C4 Model, you can drill down or zoom in & out of different levels of detail, depending on the audience you're communicating your designs to. In most software teams, this is a mix of technical (developers, architects, operations, etc.) and non-technical people (product, business stakeholders, etc.).
Using modelling, as opposed to diagramming alone, removes a lot of the maintenance headache of keeping multiple diagrams up-to-date, as changes sync automatically through all your diagrams.

Quick start guide

Getting started in IcePanel is simple. Here is a quick example to follow so you can have robust system documentation that will help you educate, learn, make decisions and plan future developments (which also look pretty cool 😎).

Step 1: Create your first context view

Step 1: Add your systems and actors
  1. 1.
    Create a landscape (if you haven't already)
  2. 2.
    Add the top-level objects for your design, such as:
    • The Software System(s) your company develops (start with 1)
    • Third-party solutions you depend on
    • People who use your solution, such as customers
Adding & editing objects in diagrams automatically adds and updates them to your model to be re-used later.

🤔 What this is for:

This is the context level (Level 1) of the C4 model, and the focus here is the big-picture view of your systems architecture. This will mostly show how your system(s) solves your customer's problems, remaining mostly at the business level, so keep it simple!

👥 Target audience;

Everyone! Anyone in or out of your company who needs a high-level overview of how your system(s) work. Perfect for your business, product or other non-technical peers and onboarding new technical teammates.

📋 Make sure to:

  1. 1.
    Name your objects in a way anyone can understand.
  2. 2.
    Label all connections so the relationships are clear.

Step 2: Zoom into a system and add your apps/stores

Step 2: Zoom into a system and add your apps and data stores
  1. 1.
    Zoom into a System (using the +🔍 icon on the top left of the system).
  2. 2.
    Add the Apps and Stores that run/are deployed inside this system.
  3. 3.
    Connect them to show the messages between or relationship of these apps & stores.

🤔 What this is for

This is the App level (Level 2 - known as Container diagram in C4). This focuses on showing the individually deployed/runnable units in each System that execute or store code.

👥 Target audience

Mainly technical people, such as architects and developers. Some product people (such as product owners, product managers or business analysts) will gain value here, especially for planning purposes.

📋 Make sure to

  1. 1.
    Name your objects in a way anyone can understand.
  2. 2.
    Label all connections so the relationships are clear.

Step 3: Add existing objects from the level above

Step 3: Add objects from Step 1 to show relationships
Because we're using a model, we can add the objects from the higher level here, too, such as other systems you depend on or the people interacting with your solution.
  1. 1.
    Add your Actors and Systems from the level above by either:
    1. 1.
      Double-clicking in the diagram and start typing their name.
    2. 2.
      Go to the "Model objects" tool on the left and drag them in.
  2. 2.
    Add the connections to the apps/stores inside the system from previously created connections.
You can create multiple diagrams to show different focuses of your model or for specific conversations with a targeted audience. Examples include customer-specific views, focus on one object, current vs future design, etc.

Step 4: Assign tech choices

Step 4: Assign tech choices
Once you have your Apps and Stores laid out and connected, start adding any tech choices you've already made, such as what service in AWS, GCP or Azure it's using, languages, libraries or frameworks, etc.
  1. 1.
    Select your model object.
  2. 2.
    Go to the technology section on the right-hand panel.
  3. 3.
    Add a new technology and search for your tech choice.
These choices come with docs preassigned and a simple explanation for those unfamiliar. These can be used later to highlight tech choices to others using the tags bar, allowing people to learn your architecture's technical choice landscape and filter your model.

Step 5: Describe each object and diagram

Step 5: Describe each object and diagram
Each object and diagram has a description, which is used to add details about that object or view. Descriptions follow that object wherever it is, and are linked to your Recommendation Score. Adding descriptions will help your teammates/audience understand how everything works in your design without needing to ask you.
The minimum you should add is a brief displayed description of what objects are responsible for, which might seem obvious to you, but helps your teammates (especially new ones).
  1. 1.
    Select an object.
  2. 2.
    Go to the right-hand panel.
  3. 3.
    Add a displayed description to each object to increase your Recommendation Score.
Try to explain:
  • What is this object
  • What are its primary responsibilities
Use the Links and Technology sections to highlight useful resources, such as the code and tech decisions.
These descriptions support Markdown, so you can quickly bring in your existing docs and formatting, manually or through our API.

Step 6: Create your first Flow​

Step 6: Create your first Flow
Your Systems architecture doesn't live in a static world without interactions and data flows, so neither should your diagrams. Flows allow you to show how your system works in multiple scenarios &/or user journeys on the same view.
  1. 1.
    Click Create flow in the diagram Flows tab at the bottom left of the screen
  2. 2.
    Select the object or connection you want to show in your first step
  3. 3.
    Click + Step on the left
  4. 4.
    Give that step a description of what's happening
  5. 5.
    Keep adding steps to show the rest of the flow
  6. 6.
    Use the Back and Next buttons to step through your flow
Once you've created your flow, go back to the beginning and run through it again to see if it makes sense. You can then check in with your teammates to see if they understand.
View your flow with arrow keys or with the Next and Back button

Step 7: Add and view Tags to show perspectives

Step 7: Add Tags to show perspectives
Tags allow you to show multiple perspectives to your diagrams without duplicating them. Use Tag groups to show different perspectives, such as deployment information, risk or cost of your model, etc.
  1. 1.
    Turn on the tags by opening the Tags bar at the bottom of the screen
  2. 2.
    Click an object to open the details in the right-hand panel
  3. 3.
    Click the Tags drop-down
  4. 4.
    Add tags that apply to the tag group you want to show (you can rename tag groups here too)
  5. 5.
    Hover over the tags in the bottom tag bar to highlight them, click on them to pin and select the hide/focus.
Tags are a great way to change the message/focus of your design with little effort and help target specific areas of focus to each of your audiences.

Step 8: Collaborate with your teammates and Share​

Step 8: Share with your teammates
IcePanel is a collaborative tool for your whole team. Getting others involved helps you gain knowledge from across your business. Get them involved by inviting them in or creating interactive share links to distribute read-only versions of your designs to external audiences. Share links are a great way to showcase your designs without them needing an account using just a browser.

Invite your teammates:

  1. 1.
    Click the Invite user icon in the top right of the screen
  2. 2.
    Type the emails of the people you want to invite to your team
  3. 3.
    Send invitations
Create share links:
  1. 1.
    Click Embed and Share in the top right of the screen
  2. 2.
    Toggle on share links (this is for your whole landscape)
  3. 3.
    Copy and paste the link to anyone you want to show off your designs to
Wherever you are when you create a share link will be where your audience lands on opening the URL. This includes position, selected object, Flow, Tags etc.

Step 9: Freeze your first version​

Step 9: Freeze your first version
You can freeze your landscapes to keep track of their evolution and use the timeline to see a visual diff of how it has evolved.
  1. 1.
    Click the Latest drop-down at the top left of the screen
  2. 2.
    Click the Freeze landscape button
  3. 3.
    Name your version and give a reason for your frozen version (this helps you and others in the future)
  4. 4.
    Go back to edit the latest and make some changes
  5. 5.
    View your previously created version to see it on the timeline and compare it with your latest

That's the basics covered!

Congratulations, you've started your journey into powerful and interactive system documentation that remains up-to-date, and all your teammates can access it!

What next?


Still need help? Let us know at [email protected], and we'll respond as soon as we can!