Getting started with the C4 model in IcePanel

⚡️ TL;DR

• Create a context diagram to show the big picture of your architecture
• Zoom in and create an app diagram to show the apps and stores that live within a system
• Add objects from the level above in the app diagram
• Assign tech choices to enhance the visuals of your diagram
• Describe each object so viewers can quickly understand the different parts of your diagram

Step 1: Create a context diagram 🎨

Start by creating a Level 1 context diagram. A context diagram is a high-level overview of your architecture that a wide range of stakeholders, both technical and non-technical, can understand. The goal of this diagram is to show how you deliver value to your customers and focus primarily on the business level, so keep it simple!

To create a context diagram:

1. Create a Landscape (if you haven’t already)
2. Create a new Context diagram from the Diagrams section of the app
3. Add top-level objects such as:
   • The system(s) your company is responsible for
   • Third-party systems you depend on
   • People who interact with your solution, like customers and employees

💡 Tip: Name your objects and connections in a way anyone can understand (avoid acronyms).

Create a Level 1 context diagram showing the different systems in your architecture

Step 2: Zoom into a system and create an app (container) diagram 🔍

Drill down into a primary system and create a Level 2 app diagram (also known as a container diagram). App diagrams show the individual deployable/runnable units in a system and their relationships. These diagrams are mainly for technical people, like architects and developers.

To create an app diagram:

1. Zoom into a system using the + 🔍 icon on the top left of the system
2. Add apps and stores by double-clicking or using the left panel
3. Add connections using the connection points on objects

💡 Tip: You can reuse lower-level connections at higher levels and vice versa. Lower connections used at higher levels will have a Lower label assigned.

Zoom into a system and add apps, stores, and connections

Step 3: Add objects from the level above ➕

With a model and hierarchy, you can add objects from Level 1, such as external systems and actors. External systems can be connected to apps and stores or expanded to show their own apps and stores.

Add actors and systems by either:

• Double-clicking in the diagram and searching for their name
• Using the left panel and dragging them in
• Connect them to the apps and stores inside the system using previously created connections

💡 Tip Avoid adding too many objects in a single diagram. Focus on the story you want to communicate (a customer-specific view, backup diagram, current vs. future design) to dictate what objects to add.

Add objects outside of the main system

Step 4: Assign tech choices 💻

Visuals make it much easier for viewers to understand what technologies an object is using. IcePanel has a catalogue of thousands of tech choices pre-populated with metadata like their description, doc links, and updates.

To assign tech choices:

1. Select the object
2. Go to the technology section on the right-hand panel
3. Search for the technology and add it to the object
4. Add as many tech choices that are relevant to the object

💡 Tip Use the tag bar to highlight different tech choices in your diagram and have more focused discussions about your architecture.

Assign tech choices to your objects

Step 5: Describe each object 💬

Each object has a detailed and display description field. We strongly recommend adding a brief displayed description to explain what the object is responsible for. Missing display descriptions is a common mistake that makes your diagram much harder to understand. Your diagram is only useful if people understand it, so adding a simple description goes a long way.

To add descriptions:

1. Select the object
2. Add a display description in the right-hand panel (120-character limit)
3. Add a detailed description (optional)

💡 Tip The detailed description field supports Markdown, so you can easily copy existing docs manually or through our API.

Describe the different objects in your diagram

🏁 Next up

We just covered the basics of getting started with IcePanel. There’s much more you can do to take your documentation to the next level, like creating a Flow, adding tags, and using Drafts. Next, we’ll talk about supplementary diagrams in the C4 model, starting with the system landscape diagram.

📚 Resources

Check out our docs for more information on all the features on IcePanel! 🧊