|
|
# C4-PlantUML
|
|
|
|
|
|
|
|
|
|
|
|
C4-PlantUML combines the benefits of [PlantUML](http://en.plantuml.com/) and the [C4 model](https://c4model.com/) 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](#getting-started)
|
|
|
* [Supported Diagram Types](#supported-diagram-types)
|
|
|
* [Snippets for Visual Studio Code](#snippets-for-visual-studio-code)
|
|
|
* [Layout Options](#layout-options)
|
|
|
* [Samples](#advanced-samples)
|
|
|
* [Background](#background)
|
|
|
* [License](#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
|
|
|
|
|
|
```c#
|
|
|
!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:
|
|
|
|
|
|
```c#
|
|
|
!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`
|
|
|
|
|
|
```csharp
|
|
|
@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 a look at the following sample of a C4 Container Diagram:
|
|
|
|
|
|
```csharp
|
|
|
@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:
|
|
|
|
|
|
```cs
|
|
|
@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](samples/C4CoreDiagrams.md).
|
|
|
|
|
|
## 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 using hidden relationships, `Lay_U`, `Lay_D`, `Lay_L`, `Lay_R`.
|
|
|
|
|
|
## 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()](LayoutOptions.md#layout_top_down-or-layout_left_right)
|
|
|
* [LAYOUT_WITH_LEGEND()](LayoutOptions.md#layout_with_legend)
|
|
|
* [LAYOUT_AS_SKETCH()](LayoutOptions.md#layout_as_sketch)
|
|
|
* [HIDE_STEREOTYPE()](LayoutOptions.md#hide_stereotype)
|
|
|
|
|
|
## Snippets for Visual Studio Code
|
|
|
|
|
|
Because the PlantUML support inside of Visual Studio Code is excellent with the [PlantUML extension](https://marketplace.visualstudio.com/items?itemName=jebbs.plantuml), you can also find VS Code snippets for C4-PlantUML at [.vscode/C4.code-snippets](.vscode/C4.code-snippets).
|
|
|
|
|
|
Project level snippets are now supported in [VSCode 1.28](https://code.visualstudio.com/updates/v1_28#_project-level-snippets).
|
|
|
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](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_creating-your-own-snippets).
|
|
|
|
|
|
|
|
|
|
|
|
## Advanced Samples
|
|
|
|
|
|
The following advanced samples are reproductions with C4-PlantUML from official [C4 model samples](https://c4model.com/#examples) created by [Simon Brown](http://simonbrown.je/).
|
|
|
|
|
|
The core diagram samples from [c4model.com](https://c4model.com/#coreDiagrams) are available [here](samples/C4CoreDiagrams.md).
|
|
|
|
|
|
### techtribes.js
|
|
|
|
|
|
Source: [C4_Container Diagram Sample - techtribesjs.puml](samples/C4_Container%20Diagram%20Sample%20-%20techtribesjs.puml)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Message Bus and Microservices
|
|
|
|
|
|
Source: [C4_Container Diagram Sample - message bus.puml](samples/C4_Container%20Diagram%20Sample%20-%20message%20bus.puml)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Background
|
|
|
|
|
|
[PlantUML](http://en.plantuml.com/) 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](http://en.plantuml.com/running).
|
|
|
|
|
|
The [C4 model](https://c4model.com/) 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](https://c4model.com/)
|
|
|
* [REAL WORLD PlantUML - Sample Gallery](https://real-world-plantuml.com/)
|
|
|
* [Visualising and documenting software architecture cheat sheets](http://www.codingthearchitecture.com/2017/04/27/visualising_and_documenting_software_architecture_cheat_sheets.html)
|
|
|
* [PlantUML and Structurizr - Create models not diagrams](http://www.codingthearchitecture.com/2016/12/08/plantuml_and_structurizr.html)
|
|
|
|
|
|
## License
|
|
|
|
|
|
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details
|