Getting started

The basics

IcePanel is an interactive modelling and diagramming tool that uses the C4 model standard to provide a structured approach to easily communicate system architectures to your many audiences.

With the C4 Model, you can zoom in & out of different levels of detail, depending on the audience you're communicating your designs to. Using modelling also removes a lot of the maintenance headache of keeping multiple diagrams up-to-date, as changes can sync automatically through all your diagrams.

1. Add/create your model objects and connect to create their relationships.
2. Zoom into your objects to show the details inside.
3. Add descriptions to those objects and diagrams to help your audience understand what and why decisions have been made.
4. Use tags & flows to look at your design with different perspectives, in a dynamic way.
5. Share your design with your teammates by inviting or using a link.

Quick start guide

Getting started in IcePanel is simple. Here is a quick example to follow, on how to design powerful system documentation that you can share and WOW your teammates.

Step 1: Add your systems and actors

First things first: create a new landscape (if you haven't already) and add in the top-level objects for your design. Adding objects in your diagram view automatically adds them to your model to be re-used later.

This is the context level (Level 1) of the C4 model and the focus here is showing the big picture view of your systems architecture ecosystem. This is a high level of detail about your System(s) and is really there for an overview of how your system(s) solve your people/customers/users problems, so keep it simple! Target audience: Anyone that needs an overview of how your system works!

1. Add in the System(s) from the tool bar on the left and name them.
2. Add in the Actors that interact with your Systems - people/customers/users
3. Connect them up showing the high level user interactions/flows

Step 1: Add your systems and actors

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

Next zoom into a System (using the +🔍 icon top left) and add the next level of detail.

This is the App level (Level 2 - known as Container diagram in C4) and the focus here is showing the individually deployed units in each System that run or store code. Target audience: mainly architects, developers and some product people.

1. Zoom in to a System (using the +🔍 icon top left)
2. Add Apps and Stores that run inside from the tool bar
3. Add icons to show the technology choices of each app and store
4. Connect these up to show how they work and the dependencies, including high level technical decisions.

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

5. Add your Actors and Systems from the level above from the "Model objects" tool to show how they're used in the ecosystem. These objects will sync changes made in all views it exists, such as naming, relationship name changes, reality links.

You can create multiple diagrams with the diagram tabs at the top, to show different focuses of the design or specific conversations. Examples include customer specific views, focus on 1 object, current vs future design , etc.

Step 2b: Add objects from Step 1 to show relationships

Step 3: Zoom into an app and add the components inside

Once you have your Apps and Stores laid out, zoom in to each App and add the Components that allow the app to run.

This is the Component level (Level 3) of the C4 model, and the main focus here is the technical details that help explain how each App works. Target audience: Architects and developers.

1. Zoom into an App (using the +🔍 icon top left)
2. Add Components, using the tool bar, that live within each App
3. Connect these up, to show how the App works with lower level technical and implementation details.
4. Bring in any other Apps, System and Actors from the Model objects tool to show end to end flows.

Hint: You can expand other systems and apps to show the low level relationships and communications using the expand icon to the right of the object name.

Step 3: Zoom into an app and add the components inside

Step 4: Describe each object and diagram

Each object and diagram has its own description tab, which is used to add details and descriptions of that 1 thing or view. Descriptions are linked to your Recommendation Score and adding descriptions will help your teammates/audience understand how everything works in your design.

1. See the diagram description panel on the right.
2. OR click an object and see the description panel on the right.
3. Add a description to each diagram and object to increase your Recommendation Score.

Try adding in:

• Description of what the view/object is
• Main responsibilities
• Technical decisions made
• Useful links

Hint: These descriptions support Markdown so you can bring in your existing docs and formatting easily.

Step 4: Describe each object and diagram

Step 5: Add Tags to show perspectives

Tags are a super cool, visual way to apply multiple perspectives on your diagrams without duplicating. Use Tag groups to show different categories or perspectives, such as technology choices, release versions, deployment information , etc.

1. Turn on the tags by opening the Tags bar at the bottom left of the screen
2. Click an object to open the details in the right-hand panel
3. Click the Tags drop down
4. Add tags that apply to the tag group you want to show (you can rename tag groups here too)
5. Hover over, click on to pin and select the hide eye to use these tags in all sorts of interesting ways.

Tags are an amazing way to completely change the message of your design with little effort and help target specific areas of focus.

Step 5: Add Tags to show perspectives

Step 6: Create your first Flow

Your Systems architecture doesn't live in a static world, without interactions and flows of data, so neither should your diagrams. Create Flows and add some steps to show the system in a real-time scenario. You can create multiple steps on the same diagram.

1. Click the Diagram flows tab in the right-hand panel
2. Click Create flow and name your sequence
3. Select the object you want to show in your first step
4. Click + Add step
5. Give that step a description
6. Keep adding steps to show the rest of the flow
7. Use the Back and Next buttons to step through your flow

Hint: you can speed up your flow creation process by selecting the connection between objects before clicking + Add step to select the sender, receiver and connection, so all you have to do is type the description!

Flows are an amazing way to display how your system is used in the real world, step-by-step.

Step 6: Create your first Flow

Step 7: Collaborate with your teammates and Share

IcePanel is a collaborative tool for your whole team, so get them involved by inviting them in or creating interactive share links to distribute read-only versions of your designs with 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. Click Invite in the top right of the screen
2. Type the email of the people you want to invite into your team
3. Send invitations

Create share links:

1. Click Share in the top right of the screen
2. Toggle on share links
3. Copy and paste the link to anyone you want to show off your designs to

Hint: you can add advanced settings to take your audience exactly where you want them and prevent them navigating to keep focus.

Step 7: Share with your teammates

Step 8: Freeze your first version

You can freeze your landscapes to keep track of the evolution and use the timeline to see a visual diff of how it has evolved over time.

1. Click the version drop down at the top of the screen in the centre
2. Click the Freeze landscape button
3. Name your version and give a reason for your frozen version
4. Go back to edit the latest and make some changes
5. View your previously created version to see it on the timeline and compare it with your latest

Step 8: Freeze your first version

That's the basics covered!

Congratulations, you've started your journey into powerful system documentation, that remains up to date and all your teammates can access it! Check out more detail on our features and advanced features here.