Some skinning to create C4 diagrams
Before you start, you need to be familiar at minimum with:
First of all you need to have plantuml up and running. For this you have multiple options (all of which will work with this):
- Local installation
- Free online editor
- VisualStudio Code Plugin: This plugin allows you to "embed" diagrams in your markdown files, which is the best of all worlds in my opinion, and is hence really recommended.
Once you have something running (or just went to planttext online editor), you can start using plantuml to create text-driven models and diagrams.
This project will help you use the awesome plantuml tool to create C4 diagrams for documenting architecture.
C4 defines a set of diagrams (core and supplamentary) that are designed to document architecture in a way that is easy to understand and communicate.
PlantUml is a uniquely pleasant-to-use tool to create diagrams from text. The fact that this is a text-driven tool opens up a lot of previously impossible scenarios:
- It is a pleasure to edit
- You don't need special tooling
- You can keep your domain models side-by-side with your code
- You can embedd models in your markdown documents in almost all major editors
- Did I mention that it is an absolute pleasure to work with plantuml?
The only real disadvantage to plantuml is that positioning can sometimes be a bit hard.
This tool allows you to use stereotypes to skin your diagram to be close to what is standard with C4. You can use this include to skin the following diagrams:
- System Context diagram
- Container diagram
- Component diagram
- System Landscape diagram
- Dynamic diagram
- Dynamic diagram
Reproduced (as closely as possible from diagrams from the official C4 model website)
-
System Context diagram
PlantUml file for diagram below
-
Container diagram
PlantUml file for diagram below
-
Component diagram
All that is needed to start is to add the following line:
!includeurl https://raw.githubusercontent.com/skleanthous/C4-PlantumlSkin/master/build/output/c4.puml
NOTE: This will set your diagram type as a deployment diagram. If you want to add some incompatible artifacts in your diagram, please also add the following statement below the
includeurloneallowmixing
-
As mentioned above, the way that you would skin your artifacts is through the use of stereotyping. Due to this, currently stereotype names are not emitted, but instead, a legend is emited on the bottom right. At this time it cannot be turned off.
-
There is support for two types of actors. Internal and external actors. The supported stereotypes are:
<<Internal>><<External>>
The following code:
@startuml !define NO_LEGEND !includeurl https://raw.githubusercontent.com/skleanthous/C4-PlantumlSkin/master/build/output/c4.puml actor Internal <<Internal>> actor External <<External>> actor InternalPerson <<Internal Person>> actor ExternalPerson <<External Person>> External -down-> Internal Internal -right-> InternalPerson InternalPerson -up-> ExternalPerson @endProduces this outcome:
-
C4 Systems can be reprensented using PlantUml rectangles and frames. In both cases the stereotypes that could be used are:
NOTE: the simplicity of rectangles makes them really useful if you want to avoid the connotations implied by UML artifacts, so they are used to represent other C4 artifacts too
<<Internal System>><<System>>(an alias to<<Internal System>>)<<External System>>
The following code:
@startuml !define NO_LEGEND !includeurl https://raw.githubusercontent.com/skleanthous/C4-PlantumlSkin/master/build/output/c4.puml rectangle Internal <<Internal System>> frame AnotherInternal <<System>> rectangle External <<External System>> frame AnotherExternal <<External System>> Internal -right-> External Internal -[hidden]down-> AnotherInternal AnotherInternal -right-> AnotherExternal @endumlProduces the outcome:
-
C4 containers can be repesented by using plantuml rectangles (and not C4 components which is a bit confusing), which are useful to be shown normally on
System Context,ContainerandSystem Landscapediagrams. The supported stereotypes are:<<Internal Container>><<Container>>(an alias toInternal Container)<<External Container>>
The following code:
@startuml !define NO_LEGEND !includeurl https://raw.githubusercontent.com/skleanthous/C4-PlantumlSkin/master/build/output/c4.puml component InternalComponent <<Internal Container>> component ExternalComponent <<External Container>> rectangle InternalRectangle <<Internal Container>> rectangle ExternalRectangle <<External Container>> InternalComponent -right-> ExternalComponent InternalComponent -[hidden]down-> InternalRectangle InternalRectangle -right-> ExternalRectangle @endumlProduces this outcome:
-
C4 components can currently only be represented by plantuml rectangles. The are only really usesful in
ComponentC4 diagrams, but obviously really important. The stereotypes used<<Internal Component>><<Component>>(an alias to<<Internal Component>>)<<External Component>>
The following code:
@startuml !define NO_LEGEND !includeurl https://raw.githubusercontent.com/skleanthous/C4-PlantumlSkin/master/build/output/c4.puml rectangle Internal <<Internal Component>> rectangle External <<External Component>> Internal -right-> External @endumlProduces this outcome:
-
The above should be enough to get you started. For more info please see:
- Complete examples
- Add skinning for C4 Code diagrams
Basically the only acknowledgement is C4-PlantUML from Ricardo Niepel. This is a very good library to work with C4, but I wanted something much more native to plantuml. Specifically I wanted to be able to work with artifacts native to plantuml (rectangle, queue, component, etc.) instead of the "method"-like means that this library exposes.