C4-PlantUML

The C4-PlantUML library allows you to create the core C4 model diagrams: System Context, Container, and Component diagrams. These diagrams follow the standard C4 modeling levels to describe software architecture at different levels of abstraction.

Available diagram types in this library include:

Core Diagrams:

• System Context Diagram: Shows the system in the context of its users and other systems.
• Container Diagram: Zooms into the system to show its high-level technical building blocks (containers).
• Component Diagram: Zooms into an individual container to show its internal components.

Supplementary Diagrams:

• System Landscape Diagram
• Dynamic Diagram
• Sequence Diagram
• Deployment Diagram

You can introduce new visual styles by defining custom tags. These tags can be applied to elements using the $tags argument and will automatically appear in the diagram legend.

Key Rules:

• Use $tags="tagname" (no space around =).
• Combine multiple tags using + (e.g., $tags="v1.0+v1.1").
• If two tags define the same skinparam, the first definition is used. To merge specific properties, define a combined tag using & in the name (e.g., AddElementTag("v1.0&v1.1", ...)).
• Avoid using commas , in tag names.
• Use SHOW_LEGEND() as the last line of your diagram to display custom tags.

To use rounded rectangles for all elements without changing the existing color scheme, set the !ROUNDED_STYLE variable to 1.

Important: This statement must be placed BEFORE any !include statements for C4 files.

@startuml
' Must be set before any C4_* file is included
!ROUNDED_STYLE=1
 
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

Person(admin, "Administrator")
System(twitter, "Twitter")

Rel(admin, twitter, "Uses")
@enduml

You can create custom themes on your local file system by duplicating an existing theme. By default, theme files should be named puml-theme-C4_foo.puml (where C4_foo is your theme name).

Unlike standard PlantUML themes that use only skinparam or style, a C4-PlantUML theme must also overwrite specific color and font variables to ensure all elements (including the legend) are updated correctly.

If you are using local copies of the C4 library files to work offline, you must tell PlantUML to look in the current directory for includes.

Command Line: Pass the -DRELATIVE_INCLUDE="." argument to the java -jar plantuml.jar command.

Visual Studio Code: Add the following to your settings.json to enable local includes in the PlantUML extension.

java -jar plantuml.jar -DRELATIVE_INCLUDE="." ...

"plantuml.jarArgs": [
  "-DRELATIVE_INCLUDE=."
]

You can use the $sprite parameter to display custom images or icons. C4-PlantUML supports several formats:

• Standard Library Sprites: Use the syntax {SpriteName} (requires the sprite to be included via !include).
• External Images: Use the syntax img:{File or Url}.
• OpenIconic: Use the syntax &{OpenIconicName}.

Customization Options:

• Scale: Adjust size using ,scale={factor} (e.g., ,scale=0.5).
• Color: Change color using ,color={color}.

When defining relationships (e.g., Rel, Rel_L, Rel_R), you can use the $sprite parameter to add icons to the connection lines. Because relationship icons are often smaller, you may need to use scaling or specific small sprites.

Techniques for relationships:

• Scaling: Use $sprite="name,scale=0.5" to prevent icons from being too large.
• Variables: Store complex sprite strings in a variable (e.g., !$mySprite="name,scale=0.5") and pass it via $sprite=$mySprite.
• OpenIconic: If the sprite string starts with &, it is treated as an OpenIconic name (e.g., $sprite="&envelope-closed").
• Custom Sprites: You can define your own small sprites using the sprite keyword.

To use C4 modeling, you must include one of the core library files at the top of your .puml file. Choose the level of detail required for your diagram:

1. Standard Library (Recommended): Uses the built-in PlantUML C4 library (no internet required).
2. Remote GitHub (Always up-to-date): Fetches the latest version from GitHub (requires internet).
3. Local Files (Offline/Custom): Use files downloaded to your local machine to ensure independence from internet connectivity.