Readme

C4 PlantUML Helper Macro

Getting up to speed with C4 is easy peasy and before you know it you have more diagram scripts than you can shake a stick at.

The issue then becomes:

• how do you standardise on alias and label names used?

• how do you pickup and maintain common descriptions?

• what are the strategies to keep diagrams clean but still balance the need for precision and detail

• how easy is it to add navigational links as the C4 maker had intended?

• is the standard C4 legend useful across a wider audience? Will folks know what a system or container is?

• easily find, reuse, extend modelled objects

• provide reports/dashboards of usage and dependancies

• How do we maintain and integrate all these scripts inorder to produce a “Model” of the architecture.

C4_Plantuml_Helper to the rescue.

Context

The following context view leverages off the Sample Enterprise Context script provided in the C4-Plantuml on Github.

@startuml enterprise context view

!include ../C4_helper.iuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
'Set Diagram settings
'=====================================================================
%set_variable_value("$C4_DIAGRAM_TYPE", "Context")
%set_variable_value("$INCLUDE_DESC", "Y")
'======================================================================
'Call procedure to build the diagram
C4_DIAGRAM(widget)

@enduml

The C4_DIAGRAM plantuml pre-processor macro is used to generate a Context diagram and to include descriptions which are sourced from the C4_diagrams.json and C4_objects.json files.

Importantly, the system description and relationship labels are sourced from the json file, rather than via the puml script.

A few tweeks to the script, and instead of rendering a description within the system objects, it is possible to output then to a table which includes links to other diagrams that this system may appear in.

@startuml enterprise context view with highlights

!include C4_helper.iuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
'Set Diagram settings
'=====================================================================
%set_variable_value("$C4_DIAGRAM_TYPE", "Context")
%set_variable_value("$INCLUDE_DESC", "N")
'======================================================================
'Call procedure to build the diagram
C4_DIAGRAM(widget)

hide braintree
'v1.1 introduces
AddElementTag("v1.1", $fontColor="black", $bgColor="gold")
AddRelTag("V1.1", $textColor="black", $lineColor="gold")
System(csaa,"CSA Assist","Customer Service Desktop used to record queries and recommend solution approach",$tags="v1.1")
Rel_L(csa,csaa,"looks up",$tags="v1.1")
'show V1.1 in legend
SHOW_LEGEND()
SHOW_OBJECT_TABLE()
taxamo .[hidden]. c4h_object_table
taxamo .[hidden]. c4h_object_table
' SHOW_LEGEND()

@enduml

The above example also demonstrates how a diagram object can be hidden, or a new one can be added without having to update the underlying json files.

Container

Add the container include and update the following variables..

container diagram example

!include https://raw.githubusercontent.com/plantuml/plantuml-stdlib/master/C4/C4_Container.puml

%set_variable_value("$C4_DIAGRAM_TYPE", "Container")
%set_variable_value("$INCLUDE_DESC", "Y")

renders the following..

Also see the BIAN Usage below for more advanced examples of Container Views.

Component

And here is the component view with an optional Information Asset details included.

component diagram example

@startuml enterprise component view
!include C4_helper.iuml
!include https://raw.githubusercontent.com/plantuml/plantuml-stdlib/master/C4/C4_Component.puml
'Set Diagram settings
'=====================================================================
%set_variable_value("$C4_DIAGRAM_TYPE", "Component")
%set_variable_value("$INCLUDE_DESC", "N")
%set_variable_value("$INCLUDE_ASSETS", "Y")
'======================================================================
'Call procedure to build the diagram
C4_DIAGRAM(widget)
SHOW_OBJECT_TABLE()
SHOW_REL_TABLE()
SHOW_ASSET_TABLE()
SHOW_LEGEND()

datatier.[hidden].c4h_object_table
datatier.[hidden].c4h_object_table
c4h_object_table.[hidden].c4h_relationship_table
c4h_relationship_table.[hidden].c4h_asset_table

@enduml

BIAN Usage

The following example demonstrates how nesting containers can be uses as a classification scheme and enabling tracability of a Software Architecture back to a Business Architecture.

The following examples leverage of Service Model provided by the Banking Industry Architecture Network

Broad and Shallow View

By defult the C4_DIAGRAM macro will process containers recursivley. To prevent this, the $DRILL_DOWN macro variable has been introduced to enable a specifc container to be presented without any of it’s children.

BIAN Container diagram example

@startuml BIAN Overview

!include C4_helper.iuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
'Set Diagram settings
'=====================================================================
%set_variable_value("$C4_DIAGRAM_TYPE", "Container")
%set_variable_value("$DRILL_DOWN", "N")
%set_variable_value("$INCLUDE_DESC", "Y")
'======================================================================
Boundary(bian,"BIAN Services") {
    $c4_diagram(bian_overview)
}

@enduml

Alternatively, using the SHOW_OBJECT_TABLE() macro, it is possible to start laying down how these concepts are relaized through out the Architecture.

BIAN Container diagram with table example

@startuml BIAN Overview with table

!include C4_helper.iuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
'Set Diagram settings
'=====================================================================
%set_variable_value("$C4_DIAGRAM_TYPE", "Container")
%set_variable_value("$DRILL_DOWN", "N")
%set_variable_value("$INCLUDE_DESC", "N")
'======================================================================
Boundary(bian,"BIAN Services") {
    $c4_diagram(bian_overview)
}

Lay_R(bian_01,bian_02)
Lay_R(bian_02,bian_03)
Lay_D(bian_01,bian_04)
Lay_D(bian_02,bian_05)
Lay_D(bian_03,bian_06)
Lay_D(bian_04,bian_07)
Lay_D(bian_05,bian_08)

SHOW_OBJECT_TABLE()
Lay_D(bian_08,c4h_object_table)
Lay_D(bian_08,c4h_object_table)

@enduml

which renders

narrow/deep

BIAN Product Container diagram with table example

@startuml BIAN Products

!include C4_helper.iuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
'Set Diagram settings
'=====================================================================
%set_variable_value("$C4_DIAGRAM_TYPE", "Container")
%set_variable_value("$DRILL_DOWN", "Y")
%set_variable_value("$INCLUDE_DESC", "N")
'======================================================================

C4_DIAGRAM(bian_products)
Lay_R(bian_mortgage_loan, bian_savings_account)
Lay_R(bian_savings_account, bian_term_deposit)
SHOW_TABLE()
SHOW_LEGEND()
Lay_D(bian_mortgage_loan,c4h_object_table)
Lay_D(bian_savings_account,c4h_object_table)

@enduml

Usage Notes

Macro Variables

The following macro variables are used

Variable	Value	Behaviour
C4_DIAGRAM	diagram identifer eg. enterprise	Displays C4 Diagram
$C4_LEVEL	CONTEXT	Container objects will have the link as per the container registary
	CONTAINER	Container objects will have a link based on the assocated context identifier. Component objects will contain a link based on teh component registry.
	COMPONENT	Components will link back to the associated container.
$INCLUDE_DESC	Y	Includes description of object from respective registry. If the variable is not set or initialised to another value, descriptions are not shown.
$DRILL_DOWN	Y	Used to control container recursion.
SHOW_OBJECT_TABLE		Displays C4 objects for the designated diagram which includes a list of diagrams this element also appears in.
SHOW_REL_TABLE		Displays C4 relationships for the designated diagram.
SHOW_ASSET_TABLE		Displays information assets referenced within the diagram.

C4_diagrams.json

Note	add code snippet and description

C4_objects.json

Note	add code snippet and description

C4_assets.json

Note	comming soone