Create C4 Container Diagram Using the Plugin API

A C4 Container Diagram is the second level of the C4 Model – a popular way to visualize software architecture. If the System Context Diagram shows the big picture, the Container Diagram zooms in one level deeper. In Visual Paradigm, you can create the C4 Container Diagram directly from the diagram editor or through the Plugin API. This article explains how to generate it programmatically using the Plugin API.

The C4 Container Diagram will be created by the plugin

Create a Blank Diagram

Begin by using DiagramManager.createDiagram with IDiagramTypeConstants.DIAGRAM_TYPE_C4_MODEL_CONTAINER_DIAGRAM to create a blank C4 Container Diagram. This initializes the workspace where all model elements and relationships will be added.

// Create blank C4 Container Diagram
DiagramManager diagramManager = ApplicationManager.instance().getDiagramManager();
IC4ModelContainerDiagramUIModel diagram = (IC4ModelContainerDiagramUIModel) diagramManager.createDiagram(IDiagramTypeConstants.DIAGRAM_TYPE_C4_MODEL_CONTAINER_DIAGRAM);
diagram.setName("Online Book Store - Container Diagram");

Create a C4 Person

After the diagram is created, you can create a C4 Person element by using IModelElementFactory. createC4modelPerson method.

// Create C4 Person model element
IC4modelPerson customer = IModelElementFactory.instance().createC4modelPerson();
customer.setName("Customer");

Once the model element is instantiated, call DiagramManager.createDiagramElement to create its corresponding view so that it appears visually on the diagram.

// Create shape for the C4 Person
IC4modelPersonUIModel customerShape = (IC4modelPersonUIModel) diagramManager.createDiagramElement(diagram, customer);
customerShape.setBounds(100, 50, 150, 140);
// Set to automatic calculate the initial caption position
customerShape.setRequestResetCaption(true);

Create a C4 System Software

A C4 System Software element typically represents the primary software system being modeled in your context diagram. To create it, start by using IModelElementFactory. createC4modelSoftwareSystem to instantiate the model element.

// Create C4 Software System Model element		
IC4modelSoftwareSystem onlineBookStore = IModelElementFactory.instance().createC4modelSoftwareSystem();
onlineBookStore.setName("Online Book Store");

After the element is created, use DiagramManager.createDiagramElement to place its view onto the diagram. This establishes the core system around which the rest of the context is defined.

// Create shape for C4 Software System 
IC4modelSoftwareSystemUIModel onlineBookStoreShape = (IC4modelSoftwareSystemUIModel) diagramManager.createDiagramElement(diagram, onlineBookStore);
onlineBookStoreShape.setBounds(340, 50, 740, 480);
// Set to automatic calculate the initial caption position
onlineBookStoreShape.setRequestResetCaption(true);

Create C4 UI Container

You can using IModelElementFactory.createC4modelContainer to create a container model element.

// Create C4 Container model element
IC4modelContainer webApp = IModelElementFactory.instance().createC4modelContainer();
webApp.setName("Web Application");
// Specify technology property
webApp.setTechnology("React, Node.js");

Once it being created you can then set it to UI container type.

// Set it as UI Container type
webApp.setContainerType(IC4modelContainer.CONTAINER_TYPE_UI_CONTAINER);

After the element is created, use the DiagramManager.createDiagramElement to place its view onto into the diagram.

// Create shape for C4 UI Container
IC4modelContainerUIModel webAppshape = (IC4modelContainerUIModel) diagramManager.createDiagramElement(diagram, webApp);
webAppshape.setBounds(360, 89, 166, 124);

Since the UI Container is contained by the System Software, we have to add both its model and views to the System Container to enforce the model structure.

// Add it as child of Online Book Store System Model
onlineBookStore.addChild(webApp);
onlineBookStoreShape.addChild(webAppshape);

Create Other Containers

You can create other containers using similar steps mentioned above. By specify different container type the element will automatically render in the correct container shape.

Create Relationships

With the key elements in place, you can proceed to define how they interact. In a C4 System Context Diagram, relationships are represented using the IC4ModelRelationship model type. You begin by creating the relationship model through IModelElementFactory.createC4modelRelationship, specifying the source and target elements.

// Create relationship model between Customer and Web Application
IC4modelRelationship relCustomerWebApp = IModelElementFactory.instance().createC4modelRelationship();
relCustomerWebApp.setName("Uses");
relCustomerWebApp.setFrom(customer);
relCustomerWebApp.setTo(webApp);

Once the relationship model is ready, use DiagramManager.createConnector to create its visual representation on the diagram, completing the contextual connections between elements.

// Create connector shape for the relationship between Customer and Web Application, and specify it's turning points. 
IC4modelRelationshipUIModel relCustomerWebAppShape = (IC4modelRelationshipUIModel) diagramManager.createConnector(diagram, relCustomerWebApp, customerShape, webAppshape, new Point[] {new Point(250, 151), new Point(360, 151)});
relCustomerWebAppShape.resetCaption();

Show the Diagram

After all elements and relationships have been added, open the diagram to display it within Visual Paradigm.

// Show up the diagram
diagramManager.openDiagram(diagram);

Sample Plugin

A sample plugin is available that demonstrates the complete process of creating a C4 Container Diagram using the Plugin API. After deploying the plugin into Visual Paradigm, you can click the plugin button in the application toolbar to run it.

Trigger the C4 Container Diagram Plugin

Download Sample Plugin

You can click the link to download the sample plugin from GitHub.