mirror of
https://github.com/plantuml-stdlib/C4-PlantUML.git
synced 2022-10-18 01:14:54 +00:00
adding pictures
using c# coloring, because plantuml is not possible at github adding layout options adding overview
This commit is contained in:
Ricardo Niepel
@@ -4,6 +4,191 @@ C4-PlantUML combines the benefits of [PlantUML](http://en.plantuml.com/) and the
|
||||
|
||||
C4-PlantUML includes macros, stereotypes, and other goodies (like VSCode Snippets) for creating C4 diagrams with PlantUML.
|
||||
|
||||
* [Getting Started](#getting-started)
|
||||
* [Snippets for Visual Studio Code](#snipptes-for-visual-studio-code)
|
||||
* [Layout Options](#layout-options)
|
||||
* [LAYOUT_TOP_DOWN or LAYOUT_LEFT_RIGHT](#layout_top_down-or-layout_left_right)
|
||||
* [LAYOUT_WITH_LEGEND](#layout_with_legend)
|
||||
* [LAYOUT_AS_SKETCH](#layout_as_sketch)
|
||||
* [Advanced Samples](#advanced-samples)
|
||||
* [Background](#background)
|
||||
|
||||
## Getting Started
|
||||
|
||||
At the top of your C4 PlantUML `.puml` file, you need to include the `C4_Container.puml` file found in the `root` of this repo.
|
||||
|
||||
To be independent of any internet connectifity, you can also download `C4_Container.puml` and reference it locally with
|
||||
|
||||
```c#
|
||||
!include path/to/C4_Container.puml
|
||||
```
|
||||
|
||||
If you want to use the always up-to-date version in this repo, use the following:
|
||||
|
||||
```c#
|
||||
!includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Container.puml
|
||||
```
|
||||
|
||||
After you have inlcluded `C4_Container.puml` you can use the defined macro definitions for the C4 elements: `Person`, `System`, `Container`, `Relationship`.
|
||||
|
||||
```csharp
|
||||
@startuml C4_Elements
|
||||
!includeurl https://raw.githubusercontent.com/RicardoNiepel/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 boundary.
|
||||
|
||||
Take a look a look at the following sample of a C4 Container Diagram:
|
||||
|
||||
```csharp
|
||||
@startuml Basic Sample
|
||||
!includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Container.puml
|
||||
|
||||
Person(admin, "Administrator")
|
||||
package "Sample System" <<boundary>> as c1 {
|
||||
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
|
||||
```
|
||||
|
||||
|
||||
|
||||
## Snippets for Visual Studio Code
|
||||
|
||||
Lorem
|
||||
|
||||
https://medium.com/hack-visual-studio-code/share-snippets-with-your-team-in-vs-code-817801e853fb
|
||||
|
||||
## Layout Options
|
||||
|
||||
PlantUML uses [Graphviz](https://www.graphviz.org/) for his graph visualization. Thus the rendering itself is done automatically for you - that it one of the biggest advantages of using PlantUML.
|
||||
|
||||
...and also sometimes one of the biggest disadvantages, if the rendering is not what the user intended.
|
||||
|
||||
For this reason, C4-PlantUML also comes with some layout options.
|
||||
|
||||
### LAYOUT_TOP_DOWN or LAYOUT_LEFT_RIGHT
|
||||
|
||||
With the two macros `LAYOUT_TOP_DOWN` and `LAYOUT_LEFT_RIGHT` it is possible to easily change the flow visualization of the diagram. `LAYOUT_TOP_DOWN` is the default.
|
||||
|
||||
```csharp
|
||||
@startuml LAYOUT_TOP_DOWN Sample
|
||||
!includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Container.puml
|
||||
|
||||
' Not needed because this is the default
|
||||
LAYOUT_TOP_DOWN
|
||||
|
||||
Person(admin, "Administrator")
|
||||
package "Sample System" <<boundary>> as c1 {
|
||||
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
|
||||
```
|
||||
|
||||
|
||||
|
||||
Using `LAYOUT_LEFT_RIGHT`
|
||||
|
||||
```csharp
|
||||
@startuml LAYOUT_LEFT_RIGHT Sample
|
||||
!includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Container.puml
|
||||
|
||||
LAYOUT_LEFT_RIGHT
|
||||
|
||||
Person(admin, "Administrator")
|
||||
package "Sample System" <<boundary>> as c1 {
|
||||
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
|
||||
```
|
||||
|
||||
|
||||
|
||||
### LAYOUT_WITH_LEGEND
|
||||
|
||||
Colors can help to add additional information or simply to make the diagram more aesthetically pleasing.
|
||||
It can also help to save some space.
|
||||
|
||||
All of that is the reason, C4-PlantUML uses colors and prefer also to enable a layout without `<<stereotypes>>` and with a legend.
|
||||
This can be enabled with `LAYOUT_WITH_LEGEND`.
|
||||
|
||||
```csharp
|
||||
@startuml LAYOUT_WITH_LEGEND Sample
|
||||
!includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Container.puml
|
||||
|
||||
LAYOUT_WITH_LEGEND
|
||||
|
||||
Person(admin, "Administrator")
|
||||
package "Sample System" <<boundary>> as c1 {
|
||||
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
|
||||
```
|
||||
|
||||
|
||||
|
||||
### LAYOUT_AS_SKETCH
|
||||
|
||||
C4-PlantUML can be especially helpful during up-front design sessions.
|
||||
One thing which is often ignored is the fact, that these software architecture sketches are just sketches.
|
||||
|
||||
Without any proof
|
||||
|
||||
* if they are technically possible
|
||||
* if they can fullfil all requirements
|
||||
* if they keep what they promise
|
||||
|
||||
More often these sketches are used by many people as facts and are manifested into their documentations.
|
||||
With `LAYOUT_AS_SKETCH` you can make a difference.
|
||||
|
||||
```csharp
|
||||
@startuml LAYOUT_AS_SKETCH Sample
|
||||
!includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Container.puml
|
||||
|
||||
LAYOUT_AS_SKETCH
|
||||
|
||||
Person(admin, "Administrator")
|
||||
package "Sample System" <<boundary>> as c1 {
|
||||
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
|
||||
```
|
||||
|
||||
|
||||
|
||||
## Advanced Samples
|
||||
|
||||
// TODO
|
||||
|
||||
## Background
|
||||
|
||||
[PlantUML](http://en.plantuml.com/) is an open source project that allows you to create UML diagrams.
|
||||
@@ -25,116 +210,4 @@ 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)
|
||||
|
||||
## Getting Started
|
||||
|
||||
At the top of your C4 PlantUML `.puml` file, you need to include the `C4_Container.puml` file found in the `root` of this repo.
|
||||
|
||||
To be independent of any internet connectifity, you can also download `C4_Container.puml` and reference it locally with
|
||||
|
||||
```plantuml
|
||||
!include path/to/C4_Container.puml
|
||||
```
|
||||
|
||||
If you want to use the always up-to-date version in this repo, use the following:
|
||||
|
||||
```plantuml
|
||||
!includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Container.puml
|
||||
```
|
||||
|
||||
After you have inlcluded `C4_Container.puml` you can use the defined macro definitions for the C4 elements: `Person`, `System`, `Container`, `Relationship`.
|
||||
|
||||
```plantuml
|
||||
@startuml Basic Sample
|
||||
!include 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 boundary.
|
||||
|
||||
Take a look a look at the following sample of a C4 Container Diagram:
|
||||
|
||||
```plantuml
|
||||
@startuml Basic Sample
|
||||
!include C4_Container.puml
|
||||
|
||||
Person(admin, "Administrator")
|
||||
package "Sample System" <<boundary>> as c1 {
|
||||
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
|
||||
```
|
||||
|
||||
## Snipptes for Visual Studio Code
|
||||
|
||||
Lorem
|
||||
|
||||
https://medium.com/hack-visual-studio-code/share-snippets-with-your-team-in-vs-code-817801e853fb
|
||||
|
||||
## Layout Options
|
||||
|
||||
PlantUML uses [Graphviz](https://www.graphviz.org/) for his graph visualization. Thus the rendering itself is done automatically for you - that it one of the biggest advantages of using PlantUML.
|
||||
|
||||
...and also sometimes one of the biggest disadvantages, if the rendering is not what the user intended.
|
||||
|
||||
For this reason, C4-PlantUML also comes with some layout options.
|
||||
|
||||
### LAYOUT_TOP_DOWN or LAYOUT_LEFT_RIGHT
|
||||
|
||||
With the two macros `LAYOUT_TOP_DOWN` and `LAYOUT_LEFT_RIGHT` it is possible to easily change the flow visualization of the diagram. `LAYOUT_TOP_DOWN` is the default.
|
||||
|
||||
```plantuml
|
||||
@startuml Basic Sample
|
||||
!include C4_Container.puml
|
||||
|
||||
' Not needed because this is the default
|
||||
LAYOUT_TOP_DOWN
|
||||
|
||||
Person(admin, "Administrator")
|
||||
package "Sample System" <<boundary>> as c1 {
|
||||
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
|
||||
```
|
||||
|
||||
Using `LAYOUT_LEFT_RIGHT`
|
||||
|
||||
```plantuml
|
||||
@startuml Basic Sample
|
||||
!include C4_Container.puml
|
||||
|
||||
LAYOUT_LEFT_RIGHT
|
||||
|
||||
Person(admin, "Administrator")
|
||||
package "Sample System" <<boundary>> as c1 {
|
||||
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
|
||||
```
|
||||
|
||||
### LAYOUT_WITH_LEGEND
|
||||
|
||||
Colors can help to add additional information or simply to make the diagram more aesthetically pleasing.
|
||||
|
||||
|
||||
## Advanced Samples
|
||||
|
||||
* [PlantUML and Structurizr - Create models not diagrams](http://www.codingthearchitecture.com/2016/12/08/plantuml_and_structurizr.html)
|
||||
Reference in New Issue
Block a user