diff --git a/README.md b/README.md index a9b4832..7d794d9 100644 --- a/README.md +++ b/README.md @@ -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 +``` + +![C4_Elements](http://www.plantuml.com/plantuml/png/ZL31IWCn4Bq7yW_hdbQecqjFdYhRtgejLSybpGxTm6GICXDA_zwmO554yVJU36_UUyoAnMOf0PjXUTmW121XhUuyEImZb8pD99BuqPXiB_tPorHEXI6xI5ArlOl17BopUOml7XAW6POFUxGaxyzR4omBvBew3bLlFK7kKqtJIgizP8xKfHcUq5jUDEtMdW3RIdP9V2IBpHhOPJzFxRrMDv_EVR8Vjs_W9eeOpzU_d5wljLleU8P_vsjr0FnU-lSYDvClZQh72cYiJ_W0 "C4_Elements") + +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" <> 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 +``` + +![Basic Sample](http://www.plantuml.com/plantuml/png/LL1DIyD04Bq7yX_6UAbG4ogUf9J687gmfJIf7iis6Tl5_M9tGYZYVtUMQejx6PZtvdtiF93mr6i5ZoB85cgXdS8qkPAcLNs7lLTm87BXeIYy6FAzf4E_wmFwrXf2GtbhTR6MhV2TNKfqg8hg_dQbXA7DuhNG8X1wNcqhvWjfqEUExT8aJLReWpKZqMbfnf2LSSf0Nf3rsKsQED5-YZr2TWe5zP6rT0RJwSxsfXF-E9k12D1Eu2jDWD_POpJWRYkSOzbtt47fdEA89At9U5LTZw6iL_dogU4JZt2NJs3nLaMiLCeE0MB306I1wpd15DqhaZ55CqZYIa1IesAl4AD-fyaftOXEC2lz4YES9cjKVqKlqJQ1htc-DCsgZhp8EiCNfMSapZ9W71_UwdytSpGTV-WF "Basic Sample") + +## 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" <> 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_TOP_DOWN Sample](http://www.plantuml.com/plantuml/png/NL5TQzj047mNw3zib8Swa4gaz2cO4E66zY6nHImtzCcifBLzvBwuMo5Cw7_l7cuIakDWuMPsTcRlDZ867es6-_hFQjDksrMp_R5wMi8QZTUKPsVAzdeSQ0mQ3im-NbTLmAdSApwCtHWfzCuoMIvxPwf7rMCOt5AH9rqjldzjD5hUFDnN1YDJaAVjGlYeB8NIo-0yoxCli7GCbcYW0JhgKMI13og2N3uG3BJ3KNEUVNAPcXiAqTaP3aRPIoZgL5NaWEn2SP5d7ljdt1CKfqImFeeHKy1ythdH3XYEDpU04VehUCapaFDcS3PHjqNlHVQ9EgYzrvAFbRE5F2tEBw5UD-NohfMMGF2jl8A7tuk4rLgxAK9QZoHm8BlnA1GZALHoqKwAPH_0of2MMJ5P_Pjd9tSpFi6Yz9-Ou3nx9FqQzDtQ9agtr5zjswmJBx7Uu7UbdyJYPQ9KTi6P3pstP0VvZNy0 "LAYOUT_TOP_DOWN Sample") + +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" <> 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_LEFT_RIGHT Sample](http://www.plantuml.com/plantuml/png/PL1TIyD047mFv3-iyQL2JQZu94KCeNv0rTAcYa_bagnwU5_SRGX5_E_kKMqHxsLWPtPdvgu22K-zLZ0lNnxNzMO-kwutoxkRsnfMGZk5QN8aJQlw3dklu9t8XOkYy6B8toIzzqqVqBVM41hAMwkBfMo5x-o3H8UggCvF5qeOMj_F2oq2eUVHfcAza0PzxjWwJTBadtiSBj07QqQYqzAC8IiZoa1UaFNPIPeuqNw8DuHibnHMMpRG6KodZUrD9_psyX94W7O2dsa2_FR6em6RZN2EppvZ0wLpYdEJj2RZKNKyXdAro1zcDQzuXBDy0lTFLUHAfUmG8DOEG1QuinCiqRqY6LFKWoJk2IGrAlOACUfNckpIZMX7ywKVOQJJP8dgj-WXsZhmDkDjNIzMKHTLU_fmwGQ9immOuTLR_MVd2at7l_mD "LAYOUT_LEFT_RIGHT Sample") + +### 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 `<>` 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" <> 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 Sample](http://www.plantuml.com/plantuml/png/PL1TIyD047mFv3-iyQL2JQZu94KCjLYXrj2aYa_bcgpryBwusn14_E_kKJyGxsLWPtPdvgu22K-zLh0id-utpVRnjbbib_ER-UeQQg6TmZGvagPLVOUzL_12vC95KNWnv7j9B_sk3-XRQmWDvQtLnLgsmdTs9T6XAcRdfvKIXZPtoqABGEXvj9snNaY3FdVidIPfyjy-JYlqmPgHwBGqOyZAY3AG5sHzTf8cJhIlOe-G7Q92_SOEEeFfT6Txqmd_Tda98a0xWVSq0Nu_pgC1TrlX79zzn1sKpYaEJjAQZ4Upup6KTPMlvWslU8IpV09t3xF8bKhP8K3i7O0iS6adMA9xHJAcQ0P9N1H8QbJi5MBKZpGvf1lHWUPBNy98fyaQrNVHtsYRmDkCYwQfwgYBgX_wzz8D4cSPCCApj_hFpXMQZh_v4m00 "LAYOUT_WITH_LEGEND Sample") + +### 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" <> 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 Sample](http://www.plantuml.com/plantuml/png/NL1DIyD04Bq7yX_6UAbG4nHFKaf340MhbYPLF8LjCkhYVh4x8OZutvsbsg9x6PZtvdti8f3mD6W5o_BvOTEqPTtMjrTDTGErq4vXcXn9qwcXny4hU2DouR8el1ZpLqblmtO8w3jh20tbdTN5MdR2z_PUeaDLL1UdAoKCRUwMXHQ1qFEghPWlf46VEtPEapJvRnvtA_J1cedejJHJoCeuPI0loFhi94sSwDx5AqAs2mhr1-lh36QphHrCB_p7V0uYG7S6dsa2_FQ-an6thN2EPPzm2wLpYcEJj2RZLNKyXR9UvVTN3PzuXFFy3EuUguYLIjanG6mTW2nmPIUOeWT5CgPeHabS4qXgLEmLOjIlDDcbcz0EPgKVOeJJP8tgj-WXsYRmDS-RfbdLaHTPU_YWT8t4MKQCuyLR_UTcWQRdJ_u6 "LAYOUT_AS_SKETCH Sample") + +## 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" <> 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" <> 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" <> 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) \ No newline at end of file