[c4-PlantUML](https://github.com/plantuml-stdlib/C4-PlantUML#getting-started) is an open source library for creating [[software architecture diagrams]] using the [C4 model](https://c4model.com/) based on [[PlantUML]]. ## Quick Start You do not need to install c4-PlantUML. Instead, simply [[include]] the `C4_Context.puml`, `C4_Container.puml` or `C4_Component.puml` file found in the `root` of the [c4-PlantUML](https://github.com/plantuml-stdlib/C4-PlantUML#getting-started) repo, depending on the type of diagram desired. 1. Create a new `.puml` file. 2. UML files start with `@startuml` and end with `@enduml`. Copy the template below to get started. ```puml @startuml !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml <specify diagram here> @enduml ``` 3. Replace the second line ( `!include...` ) with one of the following options depending on the type of diagram desired. (Note that supplementary diagram types are also available, see the [C4 Model Diagrams samples](https://github.com/plantuml-stdlib/C4-PlantUML/blob/master/samples/C4CoreDiagrams.md). ) ```bash # Context !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml # Container !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml # Component !include https://raw.githubusercontent.com/adrianvlupu/C4-PlantUML/latest/C4_Component.puml ``` 4. Use the c4-PlantUML syntax to define your diagram. See the [diagram documentation](https://github.com/plantuml-stdlib/C4-PlantUML#supported-diagram-types) for syntax specific to each diagram type. 5. To view the diagram, install the [[VS Code/PlantUML VSCode Extension]] and use `Alt + D` to display the diagram. Alternatively you can download [[PlantUML]] and use the GUI to save the image to disk or use the [PlantUML Web Server](https://www.plantuml.com/plantuml/uml/ZOxDIWGn48JlUOeufn5qSjcJfvNHsugBFsV99iqcsEc4T0VTjpSCE2AYUAeAgVwgjYosIakevytBBK824bPdaHms3pg85BuofjgtwHWbj4DZg2wJzDpaSZAliRh04ioykToZ9Nc-snbux_yUlEdGkOTj9AXJwJLAxQ5ofh4iSetHyeKUTlO0E7HpNoHcigXlW5sDosiuLojaT9_kn-aJk40Py_7q1-Znn09fv4N-swuU0ByFNbVyZlYQqmbR8DyIVW00) to display diagrams directly in your browser. To work with the files offline, download the files from the repo and include the relative path to the file instead of the raw GitHub link. ## Sprites Sprites refer to the images associated with an entity or relationship, most often a container or component. Find available sprites [here](https://github.com/tupadr3/plantuml-icon-font-sprites). To specify a sprite, define the url to the sprite library, include the `.puml` file for the sprite, and assign it to the entity. ```puml !define DEVICONS https://raw.githubusercontent.com/tupadr3/plantuml-icon-font-sprites/master/devicons !include DEVICONS/postgresql.puml Container(db, "Database", $sprite="postgresql") ``` ## Adding elements You can add custom-styled elements with the following syntax. ```plantuml AddElementTag("<tagName>", $shape=EightSidedShape(), $bgColor="CornflowerBlue", $fontColor="white", $legendText="<legend text (eight sided)>") Component(<id>, "<text>", $tags="<tagName>") ``` ## Customizing Relationships You can style relationships with the following syntax. ```puml AddRelTag("<tagName>", $textColor=$ARROW_COLOR, $lineColor=$ARROW_COLOR, $lineStyle=DashedLine()) Rel(<id1>, <id2>, "<text>", $tags="<tagName>") ``` ## Layout See this guidance for layout best practices. You can use `Rel_R()` with a relationship or use `Lay_R()` without a relationship to force a layout (`R, L, U, D` are valid). Also try the `Rel_Neighbor()` to keep elements nearby (in practice, this will establish the relationship opposite the primary layout direction, where `LAYOUT_UP_DOWN()` is default and `LAYOUT_LEFT_RIGHT` is the alternative; note that the appended directions are rotated with this layout option). ## Alternatives Diagrams written in c4-PlantUML must be rendered. You can do this manually for each graphic using the PlantUML `.jar` or the [PlantUML Web Server](https://www.plantuml.com/plantuml/uml/ZOxDIWGn48JlUOeufn5qSjcJfvNHsugBFsV99iqcsEc4T0VTjpSCE2AYUAeAgVwgjYosIakevytBBK824bPdaHms3pg85BuofjgtwHWbj4DZg2wJzDpaSZAliRh04ioykToZ9Nc-snbux_yUlEdGkOTj9AXJwJLAxQ5ofh4iSetHyeKUTlO0E7HpNoHcigXlW5sDosiuLojaT9_kn-aJk40Py_7q1-Znn09fv4N-swuU0ByFNbVyZlYQqmbR8DyIVW00). However, this can be cumbersome if you have multiple graphics. You may consider these alternatives: - [[Mermaid]] is a [[Markdown]] alternative that renders diagrams right in the browser, no additional rendering step required. However, the syntax to create a C4 diagram in Mermaid is more complicated (see [this example](https://lukemerrett.com/building-c4-diagrams-in-mermaid/)). - [[c4builder]] is a good [[command line application]] to build documentation that combines Markdown and the rendered graphics automatically, you can output a Markdown file or a [[docsify]] site.