Structuring your IcePanel C4 model

Best practices for modelling your software architecture in IcePanel using the C4 model

⚡ Tl;dr

• Spending time upfront with your team to collaborate on abstractions and boundaries will help lay a solid foundation for your model.
• Domains exist at the top level of the hierarchy and allow you to split your entire model into high-level business verticals.
• Containers in the C4 model aren’t Docker containers! We renamed containers to apps and stores in IcePanel to avoid confusion.

🚀 Let’s kick-off

We often discuss best practices on the C4 model levels and work with IcePanel users to start their modelling journey with a good structure. We also highlight the bells and whistles IcePanel provides on top of the C4 model to help enterprises scale the methodology to hundreds of software systems.

We’ll summarize our advice below and help you lay a solid foundation moving forwards.

🧑‍💻 Upfront collaborative discussion

Our first advice is to collaboratively decide on a strategy for defining your C4 model abstractions. If you’re developing a new common language and you hope everyone will adopt it, then getting other people involved early will help fuel adoption across your teams.

If your team is unfamiliar with the C4 model, then this discussion needs to begin with an overview of the C4 model and its layered approach. It’s important to have a basic understanding before you dive into discussions about where to draw boundaries at each level.

🗃️ The IcePanel hierarchy

The IcePanel levels are similar to the C4 model, with a few differences. We made changes in areas we feel are important to achieve our vision of autonomous teams working in a scaled C4 model. We’ll do a quick overview and then dive into each level in detail with examples.

• Level 0 - Domains
  • Segment your entire model and diagrams based on high-level business verticals.
• Level 1 - Systems
  • Logical groups of apps and stores that provide value to another user or system.
  • Usually owned by a development team or department.
• Level 2 - Apps and Stores
  • Independently deployable or runnable services or storage.
• Level 3 - Components
  • Modules or packages defined in source code.
• Level 4 - Reality
  • Links to resources in the real world, such as source control or cloud objects.

0️⃣ Identify domains from your business verticals

When talking about level 0, people are usually referring to the supplementary system landscape diagram, which is not part of the 4 C’s. We took a different approach with IcePanel by introducing domains.

Domains exist at the top level of the hierarchy and allow you to split your entire model and diagrams into many high-level business verticals. We introduced this after our enterprise teams struggled to organize large numbers of software systems and context diagrams.

You can read more about our approach when building domains.

Domains are highly tailored to your business or industry. For example, a supermarket may have domains such as:

• Retail
• Logistics
• Vendors
• Payments

1️⃣ Define your systems

The 1st level of the C4 model stands for context, containing software systems and the people that interact with those software systems. Software systems are logical groups of applications and data stores that provide value to a group of users or system.

A common question when getting started with the C4 model is where you should draw the boundaries between systems. The C4 model website advises that a system should be owned by a single development team. Depending on your team structure, you may want to discuss the best approach.

You can read more about two methods (bottom-up and top-down) for defining the boundaries between systems.

Examples of systems could be:

• Card payments: Responsible for card capture, charging and refunds.
• Stock control: Responsible for keeping track of inventory count
• Product shipping: Responsible for shipping labels, quotes and tracking

Systems also include your external dependencies such as:

• Stripe: Payment gateway
• SendGrid: Email provider
• Google Analytics: User tracking

2️⃣ Create apps and stores

The 2nd level of the C4 model stands for containers which are applications or data stores that are independently deployable or runnable. Containers are a boundary inside which code is executed, or data is stored.

Before you ask, containers in the C4 model aren’t Docker containers! To avoid confusion, we split and renamed containers to apps and stores in IcePanel.

If your architecture is distributed, you’ll likely spend more time working at this 2nd level.

Examples of apps could be:

• Shipping API: REST API
• Mobile app: Customer facing iOS app
• Payments webhook: Serverless webhook for payment notifications

Examples of stores could be:

• Inventory database
• Thumbnail storage

3️⃣ Add components

The 3rd level of the C4 model is components, which are the modules or building blocks for your apps and stores. Components are code-level boundaries and are deployed together.

If your architecture is monolithic, you’ll likely have more complexity at this 3rd level.

Examples of app components could be:

• Shipping quote module
• Shipping tracking module
• Mobile app tracking package

Examples of store components could be:

• Users table in a database
• Images folder in a bucket

4️⃣ Link to reality

The 4th level of the C4 model is code where you would usually find UML class diagrams. This level is less common and usually seen as too much detail for agile teams. The C4 model website suggests that this level should be automatically generated as the high rate of change would make it difficult to maintain manually.

Rather than diagramming the code level in IcePanel, we decided to link objects from higher abstract levels to tangible resources in the real world. These can be links to source control, cloud objects, websites or wiki pages. This allows viewers to quickly access places where these resources exist in reality and also informs maintainers when links no longer exist so the model can be updated.

Examples of links to reality could be:

• Shipping quote module linking to a folder in source control.
• Shipping API linking to a repository in source control.
• Payments webhook linking to a serverless function in GCP.
• Stripe external system can link to a management interface.
• Database can link to an internal wiki page.

🏁 To wrap up

We covered the most important IcePanel object types you need to know to start creating a good structure for your model.

Again, spending time upfront with your team to collaborate on abstractions and boundaries can play huge dividends later in your modelling journey. We find that collaboratively modelling your systems leads to deeper discussions and helps your team think about your architecture in new ways. Try having a collaborative discussion about modelling your architecture, you’ll find it a helpful exercise!

Let us know in the comments if you have any insights on structuring your IcePanel model.

Stay chill 🧊

ℹ️ Infographic

Download here