C4-PlantUML

C4-PlantUML combines the benefits of PlantUML and the C4 model for providing a simple way of describing and communicate software architectures – especially during up-front design sessions – with an intuitive language using open source and platform independent tools.

C4-PlantUML includes macros, stereotypes, and other goodies (like VSCode Snippets) for creating C4 diagrams with PlantUML.

• Getting Started
• Supported Diagram Types
• Snippets for Visual Studio Code
• Layout Options
• Samples
• Background
• License

Getting Started

At the top of your C4 PlantUML .puml file, you need to include the C4_Context.puml, C4_Container.puml or C4_Component.puml file found in the root of this repo.

To be independent of any internet connectivity, you can also download the files found in the root and reference it locally with

!include path/to/C4.puml
!include path/to/C4_Context.puml
!include path/to/C4_Container.puml
!include path/to/C4_Component.puml

Just remember to change the !include statements at the top of the files.

If you want to use the always up-to-date version in this repo, use the following:

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

Now let's create a C4 Container diagram:

After you have included C4_Container.puml you can use the defined macro definitions for the C4 elements: Person, Person_Ext, System, System_Ext, Container, Relationship, Boundary, and System_Boundary

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

Person(personAlias, "Label", "Optional Description")
Container(containerAlias, "Label", "Technology", "Optional Description")
System(systemAlias, "Label", "Optional Description")

Rel(personAlias, containerAlias, "Label", "Optional Technology")
@enduml

In addition to this, it is also possible to define a system or component boundary.

Take a look at the following sample of a C4 Container Diagram:

@startuml Basic Sample
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

Person(admin, "Administrator")
System_Boundary(c1, "Sample System") {
    Container(web_app, "Web Application", "C#, ASP.NET Core 2.1 MVC", "Allows users to compare multiple Twitter timelines")
}
System(twitter, "Twitter")

Rel(admin, web_app, "Uses", "HTTPS")
Rel(web_app, twitter, "Gets tweets from", "HTTPS")
@enduml

Entities can also be decorated with icons using the last parameter, for example:

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

!define DEVICONS https://raw.githubusercontent.com/tupadr3/plantuml-icon-font-sprites/master/devicons
!define FONTAWESOME https://raw.githubusercontent.com/tupadr3/plantuml-icon-font-sprites/master/font-awesome-5
!include DEVICONS/angular.puml
!include DEVICONS/java.puml
!include DEVICONS/msql_server.puml
!include FONTAWESOME/users.puml

LAYOUT_WITH_LEGEND()

Person(user, "Customer", "People that need products", "users")
Container(spa, "SPA", "angular", "The main interface that the customer interacts with", "angular")
Container(api, "API", "java", "Handles all business logic", "java")
ContainerDb(db, "Database", "Microsoft SQL", "Holds product, order and invoice information", "msql_server")

Rel(user, spa, "Uses", "https")
Rel(spa, api, "Uses", "https")
Rel_R(api, db, "Reads/Writes")
@enduml

Supported Diagram Types

Diagram types

• System Context & System Landscape diagrams
  • Import: !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
  • Macros:
    • Person(alias, label, ?description, ?sprite)
    • Person_Ext
    • System(alias, label, ?description, ?sprite)
    • System_Ext
    • Boundary(alias, label, ?type)
    • Enterprise_Boundary(alias, label)
    • System_Boundary
• Container diagram
  • Import: !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
  • Additional Macros:
    • Container(alias, label, technology, ?description, ?sprite)
    • ContainerDb
    • ContainerQueue
    • Container_Ext
    • ContainerDb_Ext
    • ContainerQueue_Ext
    • Container_Boundary(alias, label)
• Component diagram
  • Import: !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml
  • Additional Macros:
    • Component(alias, label, technology, ?description, ?sprite)
    • ComponentDb
    • ComponentQueue
    • Component_Ext
    • ComponentDb_Ext
    • ComponentQueue_Ext
• Dynamic diagram
  • Import: !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Dynamic.puml
  • Additional Macros:
    • RelIndex(index, from, to, label)
    • increment()
    • setIndex(number)
• Deployment diagram
  • Import: !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Deployment.puml
  • Additional Macros:
    • Deployment_Node(alias, label, ?type)

Take a look at each of the C4 Model Diagram Samples.

Relationship Types

• Rel(from, to, label, ?technology)
• BiRel (bidirectional relationship)

You can force the direction of a relationship by using:

• Rel_U, Rel_Up
• Rel_D, Rel_Down
• Rel_L, Rel_Left
• Rel_R, Rel_Right

In rare cases, you can force the layout of objects which have no relationships by using:

• Lay_U
• Lay_D
• Lay_L
• Lay_R

In following sample a person uses different systems, and group of persons which have no relations

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
HIDE_STEREOTYPE()

Person(a, "A")
Person(b, "B")
Person(c, "C")
Person(d, "D")
Person(e, "E")

Lay_U(a, b)
Lay_R(a, c)
Lay_D(a, d)
Lay_L(a, e)

Person(x, "X")
System(s1, "S1")
System(s2, "S2")
System(s3, "S3")
System(s4, "S4")

Rel_U(x, s1, "uses")
Rel_R(x, s2, "uses")
Rel_D(x, s3, "uses")
Rel_L(x, s4, "uses")
@enduml

Layout Options

C4-PlantUML also comes with some layout options to make it easy and reuseable to create nice and useful diagrams:

• LAYOUT_TOP_DOWN() or LAYOUT_LEFT_RIGHT()
• LAYOUT_WITH_LEGEND()
• LAYOUT_AS_SKETCH()
• HIDE_STEREOTYPE()

Snippets for Visual Studio Code

Because the PlantUML support inside of Visual Studio Code is excellent with the PlantUML extension, you can also find VS Code snippets for C4-PlantUML at .vscode/C4.code-snippets.

Project level snippets are now supported in VSCode 1.28. Just include the C4.code-snippets file in the .vscode folder of your project.

It is possible to save them directly inside VS Code: Creating your own snippets.

Advanced Samples

The following advanced samples are reproductions with C4-PlantUML from official C4 model samples created by Simon Brown.

The core diagram samples from c4model.com are available here.

techtribes.js

Source: C4_Container Diagram Sample - techtribesjs.puml

Message Bus and Microservices

Source: C4_Container Diagram Sample - message bus.puml

Background

PlantUML is an open source project that allows you to create UML diagrams. Diagrams are defined using a simple and intuitive language. Images can be generated in PNG, in SVG or in LaTeX format.

PlantUML was created to allow the drawing of UML diagrams, using a simple and human readable text description. Because it does not prevent you from drawing inconsistent diagrams, it is a drawing tool and not a modeling tool. It is the most used text-based diagram drawing tool with extensive support into wikis and forums, text editors and IDEs, use by different programming languages and documentation generators.

The C4 model for software architecture is an "abstraction-first" approach to diagramming, based upon abstractions that reflect how software architects and developers think about and build software. The small set of abstractions and diagram types makes the C4 model easy to learn and use. C4 stands for context, containers, components, and code — a set of hierarchical diagrams that you can use to describe your software architecture at different zoom levels, each useful for different audiences.

The C4 model was created as a way to help software development teams describe and communicate software architecture, both during up-front design sessions and when retrospectively documenting an existing codebase.

More information can be found here:

• The C4 model for software architecture
• REAL WORLD PlantUML - Sample Gallery
• Visualising and documenting software architecture cheat sheets
• PlantUML and Structurizr - Create models not diagrams

License

This project is licensed under the MIT License - see the LICENSE file for details