plantUML for C4 model汉化(todo)

C4-PlantUML 结合了 PlantUML 和 C4 模型的优点，通过使用开源和平台独立工具的直观语言，提供了一种描述和交流软件架构的简单方法——尤其是在前期设计会议期间。 C4-PlantUML 包括用于使用 PlantUML 创建 C4 图的宏、构造型和其他好东西（如 VSCode 片段）。

原文地址: plantuml-stdlib/C4-PlantUML

入门

在你的 C4 PlantUML .puml 文件的顶部，你需要在这个 repo 的 root目录中找到的 C4_Context.puml、C4_Container.puml 或 C4_Component.puml 文件。 要独立于任何 Internet 连接，您还可以将它下载下来,在 root目录中找到的文件，并使用附加命令行参数 -DRELATIVE_INCLUDE="."（包括本地文件）激活本地转换

java -jar plantuml.jar -DRELATIVE_INCLUDE="."  ...

如果要在此 repo 中使用始终最新的版本，请使用以下命令：

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

现在让我们创建一个 C4 容器图：

(如果您不想在本地运行 PlantUML，您可以使用 e.g. the PlantUML Web Server.)

包含 C4_Container.puml 后，您可以使用 C4 元素定义的宏定义：“Person”、“Person_Ext”、“System”、“System_Ext”、“Container”、“Relationship”、“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

除此之外，还可以定义系统或组件边界。

查看以下 C4 容器图示例：

@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 也可以使用 图标/sprites 装饰 使用 $sprite 参数, 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", $sprite="users")
Container(spa, "SPA", "angular", "The main interface that the customer interacts with", $sprite="angular")
Container(api, "API", "java", "Handles all business logic", $sprite="java")
ContainerDb(db, "Database", "Microsoft SQL", "Holds product, order and invoice information", $sprite="msql_server")

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

和 icons/sprites 设置相似，我们也可以对所有元素和关系添加链接:

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

Person(admin, "Administrator", $sprite="person2", $link="https://github.com/plantuml-stdlib/C4-PlantUML/blob/master/LayoutOptions.md#hide_person_sprite-or-show_person_spritesprite")
System_Boundary(c1, "Sample System", $link="https://github.com/plantuml-stdlib/C4-PlantUML") {
    Container(web_app, "Web Application", "C#, ASP.NET Core 2.1 MVC", $descr="Allows users to compare multiple Twitter timelines", $link="https://github.com/plantuml-stdlib/C4-PlantUML/blob/master/LayoutOptions.md")
}
System(twitter, "Twitter", $link="https://github.com/plantuml-stdlib/C4-PlantUML")

Rel(admin, web_app, "Uses", "HTTPS", $link="https://plantuml.com/link")
Rel(web_app, twitter, "Gets tweets from", "HTTPS", $link="https://plantuml.com/link")
@enduml

png 本身不支持链接，因此下图生成为 svg 图像。 Github 不支持 README.md 中的 svg 链接。 如果您单击图像，则会打开一个新窗口，您可以在那里使用链接。

元素和关系可以用标签装饰，并通过计算出的图例进行解释，例如：

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

AddElementTag("v1.0", $borderColor="#d73027")
AddElementTag("v1.1", $fontColor="#d73027")
AddElementTag("backup", $fontColor="orange")

AddRelTag("backup", $textColor="orange", $lineColor="orange", $lineStyle = DashedLine())

Person(user, "Customer", "People that need products")
Person(admin, "Administrator", "People that administrates the products via the new v1.1 components", $tags="v1.1")
Container(spa, "SPA", "angular", "The main interface that the customer interacts with via v1.0", $tags="v1.0")
Container(spaAdmin, "Admin SPA", "angular", "The administrator interface that the customer interacts with via new v1.1", $tags="v1.1")
Container(api, "API", "java", "Handles all business logic (incl. new v1.1 extensions)", $tags="v1.0+v1.1")
ContainerDb(db, "Database", "Microsoft SQL", "Holds product, order and invoice information")
Container(archive, "Archive", "Audit logging", "Stores 5 years", $tags="backup")

Rel(user, spa, "Uses", "https")
Rel(spa, api, "Uses", "https")
Rel_R(api, db, "Reads/Writes")
Rel(admin, spaAdmin, "Uses", "https")
Rel(spaAdmin, api, "Uses", "https")
Rel_L(api, archive, "Writes", "messages", $tags="backup")

SHOW_LEGEND()
@enduml

支持的图表类型

• arg.. 参数为必需的 (e.g. alias)
• ?arg.. 参数为可选的 (e.g. ?descr)
• *techn .. 技术参数是必需的, 但是如果技术参数通过 $tag 来定义，那么不需要techn参数

• 系统 Context & 系统景观图
  • Import: !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/**C4_Context.puml**
  • 宏:
    • Person(alias, label, ?descr, ?sprite, ?tags, $link)
    • Person_Ext
    • System(alias, label, ?descr, ?sprite, ?tags, $link)
    • SystemDb
    • SystemQueue
    • System_Ext
    • SystemDb_Ext
    • SystemQueue_Ext
    • Boundary(alias, label, ?type, ?tags, $link)
    • Enterprise_Boundary(alias, label, ?tags, $link)
    • System_Boundary
• Container图
  • Import: !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/**C4_Container.puml**
  • Additional Macros:
    • Container(alias, label, *techn, ?descr, ?sprite, ?tags, $link)
    • ContainerDb
    • ContainerQueue
    • Container_Ext
    • ContainerDb_Ext
    • ContainerQueue_Ext
    • Container_Boundary(alias, label, ?tags, $link)
• Component图
  • Import: !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/**C4_Component.puml**
  • 附加宏:
    • Component(alias, label, *techn, ?descr, ?sprite, ?tags, $link)
    • ComponentDb
    • ComponentQueue
    • Component_Ext
    • ComponentDb_Ext
    • ComponentQueue_Ext
• 动态图
  • Import: !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/**C4_Dynamic.puml**
  • 附加宏:
    • RelIndex(index, from, to, label, ?tags, $link)
    • (lowercase) increment($offset=1): 增加当前索引（没有直接输出的程序）
    • (lowercase) setIndex($new_index): 设置新索引（没有直接输出的过程）
    • LastIndex(): 返回最后使用的索引（可以用作参数的函数）

    以下 2 个宏需要 V1.2020.24Beta4（已经可以使用 https:www.plantuml.complantuml 进行测试）

    • Index($offset=1): 返回当前索引并计算下一个索引（可用作参数的函数）
    • SetIndex($new_index): 返回新的集合索引并计算下一个索引（可用作参数的函数）
• 部署图

  • Import: !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/**C4_Deployment.puml**

  • 附加宏:
    • Deployment_Node(alias, label, ?type, ?descr, ?sprite, ?tags, $link)
    • Node(alias, label, ?type, ?descr, ?sprite, ?tags, $link): Deployment_Node() 的简称
    • Node_L(alias, label, ?type, ?descr, ?sprite, ?tags, $link): Node()-左对齐
    • Node_R(alias, label, ?type, ?descr, ?sprite, ?tags, $link): Node()-右对齐

查看每个 C4 模型图示例。

关系类型

• Rel(from, to, label, ?techn, ?descr, ?sprite, ?tags, $link)
• BiRel (双向关系)

您可以使用以下方法强制关系的方向：

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

关系对应的 sprites 通常较小，因此以下设置可选:

• 使用较小的图标（如以下示例中的三角形）
• 使用额外的比例因子（直接作为参数的一部分，或通过变量）
• 如果 sprite 参数以 & 开头，也可以使用 OpenIconic 名称（详情参见 https:useiconic.comopen）

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

Person(user, "User")
Person(user1, "User 1")
Person(user2, "User 2")
Person(user3, "User 3")

System(system, "System")

' normal sprites are too big 
Rel_L(user, user2, "informs", "courier", "normal sprites are too big", $sprite="person2")

' scaled sprites are ok
Rel_R(user, user3, "informs", "courier", "scaled sprites are OK", $sprite="person2,scale=0.5")

' combine sprite and scale to a new sprite
!$combinedSprite="person2,scale=0.5"
Rel_R(user, user3, "informs", "courier", "combined sprites are OK", $sprite=$combinedSprite)


' special smaller sprites can be used
sprite $triangle {
    00000000000
    00000F00000
    0000FBF0000
    0000FBF0000
    000F999F000
    000F999F000
    00F66666F00
    00F66666F00
    0F3333333F0
    0F3333333F0
    0FFFFFFFFF0
    00000000000
}
Rel_R(user1, system, "orders", "http", "small sprites, like the small triangle", $sprite="triangle")

' if sprite starts with &, sprite defines a OpenIconic, details see https://useiconic.com/open/
Rel_D(user, user1, "requests", "async message", "if sprite starts with &, it defines a OpenIconic like &envelope-closed", $sprite = "&envelope-closed")
@enduml

在极少数情况下，您可以使用以下方法强制没有关系的对象的布局：

• Lay_U(from, to)
• Lay_D(from, to)
• Lay_L(from, to)
• Lay_R(from, to)

在以下示例中，一个人使用不同的系统，以及没有关系的一组人

@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

（结合 SHOW_FLOATING_LEGEND()）元素和例如可能需要所有的浮动图例，例如可以到达绘图区域的角落。

• Lay_Distance(from, to, ?distance): 使用向下对齐设置 from 和 to 之间的距离（Lay_Distance(from,to,0) 等于 Lay_D(from, to)）。浮动图例的默认别名是 LEGEND()。

在以下示例中，浮动图例应位于图形的左下角。 （正常的 SHOW_LEGEND() 调用不需要额外的 Lay_Distance() 调用，图例会自动绘制在右侧图表下方）

@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

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

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

SHOW_FLOATING_LEGEND()
Lay_Distance(LEGEND(), db, 1)
@enduml

布局选项

C4-PlantUML 还带有一些布局选项，使创建漂亮有用的图表变得容易和可重用：

• LAYOUT_TOP_DOWN() or LAYOUT_LEFT_RIGHT() or LAYOUT_LANDSCAPE()
• LAYOUT_WITH_LEGEND() or SHOW_LEGEND(?hideStereotype)
• SHOW_FLOATING_LEGEND(?alias, ?hideStereotype) and LEGEND()
• LAYOUT_AS_SKETCH()
• HIDE_STEREOTYPE()

C4-PlantUML 还带有一些 person sprite/portrait 选项:

• HIDE_PERSON_SPRITE()
• SHOW_PERSON_SPRITE(?sprite)
• SHOW_PERSON_PORTRAIT()
• SHOW_PERSON_OUTLINE() (requires PlantUML version >= 1.2021.4)

Custom tags/stereotypes 支持和皮肤参数更新

可以将附加标签构造型添加到现有元素构造型（组件、…）和突出显示、…特定方面：

• AddElementTag(tagStereo, ?bgColor, ?fontColor, ?borderColor, ?shadowing, ?shape, ?sprite, ?techn, ?legendText, ?legendSprite): Introduces a new element tag. The styles of the tagged elements are updated and the tag is displayed in the calculated legend.
• AddRelTag(tagStereo, ?textColor, ?lineColor, ?lineStyle, ?sprite, ?techn, ?legendText, ?legendSprite): Introduces a new relation tag. The styles of the tagged relations are updated and the tag is displayed in the calculated legend.
• UpdateElementStyle(elementName, ?bgColor, ?fontColor, ?borderColor, ?shadowing, ?shape, ?sprite, ?techn, ?legendText, ?legendSprite): This call updates the default style of the elements (component, …) and creates no additional legend entry.
• UpdateRelStyle(textColor, lineColor): This call updates the default relationship colors and creates no additional legend entry.
• RoundedBoxShape(): This call returns the name of the rounded box shape and can be used as ?shape argument.
• EightSidedShape(): This call returns the name of the eight sided shape and can be used as ?shape argument.
• DashedLine(): This call returns the name of the dashed line and can be used as ?lineStyle argument.
• DottedLine(): This call returns the name of the dotted line and can be used as ?lineStyle argument.
• BoldLine(): This call returns the name of the bold line and can be used as ?lineStyle argument.

Each element can be extended with one or multiple custom tags via the keyword argument $tags="...", like Container(spaAdmin, "Admin SPA", $tags="v1.1"). Multiple tags can be combined with +, like Container(api, "API", $tags="v1.0+v1.1").

Element specific tag definitions

Sometimes an added element tag is element specific and all element specific colors should be used, e.g. a specific user role should be defined as element tag with the specific colors ...PERSON_... like

AddElementTag("admin", $fontColor=$ELEMENT_FONT_COLOR, $bgColor=$PERSON_BG_COLOR, $borderColor=$PERSON_BORDER_COLOR, $sprite="osa_user_audit", $legendText="administration user")

Therefore element Add…Tag() shortcuts are added which use the specific colors as default values and the call can be simplified like

AddPersonTag("admin", $sprite="osa_user_audit", $legendText="administration user")

Following calls introduces new element tags with element specific default colors:

• AddPersonTag(tagStereo, ?bgColor, ?fontColor, ?borderColor, ?shadowing, ?shape, ?sprite, ?legendText, ?legendSprite)
• AddExternalPersonTag(tagStereo, ?bgColor, ?fontColor, ?borderColor, ?shadowing, ?shape, ?sprite, ?legendText, ?legendSprite)
• AddSystemTag(tagStereo, ?bgColor, ?fontColor, ?borderColor, ?shadowing, ?shape, ?sprite, ?legendText, ?legendSprite)
• AddExternalSystemTag(tagStereo, ?bgColor, ?fontColor, ?borderColor, ?shadowing, ?shape, ?sprite, ?legendText, ?legendSprite)
• AddComponentTag(tagStereo, ?bgColor, ?fontColor, ?borderColor, ?shadowing, ?shape, ?sprite, ?techn, ?legendText, ?legendSprite)
• AddExternalComponentTag(tagStereo, ?bgColor, ?fontColor, ?borderColor, ?shadowing, ?shape, ?sprite, ?techn, ?legendText, ?legendSprite)
• AddContainerTag(tagStereo, ?bgColor, ?fontColor, ?borderColor, ?shadowing, ?shape, ?sprite, ?techn, ?legendText, ?legendSprite)
• AddExternalContainerTag(tagStereo, ?bgColor, ?fontColor, ?borderColor, ?shadowing, ?shape, ?techn, ?sprite, ?legendText, ?legendSprite)
• AddNodeTag(tagStereo, ?bgColor, ?fontColor, ?borderColor, ?shadowing, ?shape, ?sprite, ?techn, ?legendText, ?legendSprite) (node specific: $type reuses $techn definition of $tags)

Comments

• SHOW_LEGEND() supports the customized stereotypes (LAYOUT_WITH_LEGEND() cannot be used, if the custom tags/stereotypes should be displayed in the legend).
• SHOW_LEGEND() has to be last line in diagram.
• Don’t use space between $tags and = (PlantUML does not support it).
• Don’t use , as part of the tag names (PlantUML does not support it in combination with keyword arguments).
• If 2 tags defines the same skinparam, the first definition is used.

• If specific skinparams have to be merged (e.g. 2 tags change the font color) an additional combined tag has to be defined. Use & as part of combined tag names.

• Colors of relationship tags cannot be automatically merged (PlantUML does not support it). If one tag modifies the line color and the other the text color, an additional combined tag has to be defined and used.

Sample with different tag combinations

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

UpdateElementStyle(person, $fontColor="green")
AddElementTag("v1.0", $fontColor="#d73027", $borderColor="#d73027")
AddElementTag("v1.1", $fontColor="#ffffbf", $borderColor="#ffffbf")
AddElementTag("v1.0&v1.1", $fontColor="#fdae61", $borderColor="#fdae61")
AddElementTag("fallback", $bgColor="#444444")

AddElementTag("micro service", $shape=EightSidedShape())
AddElementTag("storage", $shape=RoundedBoxShape())

UpdateRelStyle(black, black)
AddRelTag("service1", $textColor="red")
AddRelTag("service2", $lineColor="red")
AddRelTag("service1&service2", $textColor="red", $lineColor="red")

Container(spa, "SPA", "angular", "The main interface that the customer interacts with via v1.0", $tags="v1.0")
Container(spaAdmin, "Admin SPA", "angular", "The administrator interface that the customer interacts with via new v1.1", $tags="v1.1")
Container(api, "API", "java", "Handles all business logic (incl. new v1.1 extensions)", $tags="v1.0&v1.1+v1.0+v1.1")
Container(spa2, "SPA2", "angular", "The main interface that the customer interacts with via v1.0", $tags="v1.0+fallback")
Container(spaAdmin2, "Admin SPA2", "angular", "The administrator interface that the customer interacts with via new v1.1", $tags="fallback+v1.1")

Container(services, "Services", "techn", $tags="micro service")
Container(fileStorage, "File storage", "techn", $tags="storage")

Rel(spa, api, "Uses", "https")
Rel(spaAdmin, api, "Uses", "https")
Rel_L(spa, spa2, "Updates", "https")
Rel_R(spaAdmin, spaAdmin2, "Updates", "https")

Rel_D(api, services, "uses service1 via this call", $tags="service1")
Rel_D(api, services, "uses service2 via this call", $tags="service2")
Rel_D(services, fileStorage, "both services stores via this call", $tags="service1&service2+service1+service2")

SHOW_LEGEND(false)
@enduml

Sample with tag dependent sprites and custom legend text

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

!define osaPuml https://raw.githubusercontent.com/Crashedmind/PlantUML-opensecurityarchitecture2-icons/master
!include osaPuml/Common.puml
!include osaPuml/User/all.puml

!include <office/Servers/database_server>
!include <office/Servers/file_server>
!include <office/Servers/application_server>
!include <office/Concepts/service_application>
!include <office/Concepts/firewall>

AddExternalPersonTag("anonymous_ext", $sprite="osa_user_black_hat", $legendText="anonymous user")
AddPersonTag("customer", $sprite="osa_user_large_group", $legendText="aggregated user")
AddPersonTag("admin", $sprite="osa_user_audit,color=red", $legendSprite="osa_user_audit,scale=0.25,color=red", $legendText="administration user")

AddContainerTag("webApp", $sprite="application_server", $legendText="web app container")
AddContainerTag("db", $sprite="database_server", $legendText="database container")
AddContainerTag("files", $sprite="file_server", $legendText="file server container")
AddContainerTag("conApp", $sprite="service_application", $legendText="console app container")

AddRelTag("firewall", $textColor="$ARROW_COLOR", $lineColor="$ARROW_COLOR", $sprite="firewall,scale=0.3,color=red", $legendText="firewall")

Person_Ext(anonymous_user, "Bob", $tags="anonymous_ext")
Person(aggregated_user, "Sam, Ivone", $tags="customer")
Person(administration_user, "Bernd", $tags="admin")

System_Boundary(c1, "techtribes.js"){
    Container(web_app, "Web Application", "Java, Spring MVC, Tomcat 7.x", $tags="webApp")
    ContainerDb(rel_db, "Relational Database", "MySQL 5.5.x", $tags="db")
    Container(filesystem, "File System", "FAT32", $tags="files")
    ContainerDb(nosql, "NoSQL Data Store", "MongoDB 2.2.x", $tags="db")
    Container(updater, "Updater", "Java 7 Console App", $tags="conApp")
}

Rel(anonymous_user, web_app, "Uses", "HTTPS", $tags="firewall")
Rel(aggregated_user, web_app, "Uses", "HTTPS", $tags="firewall")
Rel(administration_user, web_app, "Uses", "HTTPS", $tags="firewall")

Rel(web_app, rel_db, "Reads from and writes to", "SQL/JDBC, port 3306")
Rel(web_app, filesystem, "Reads from")
Rel(web_app, nosql, "Reads from", "MongoDB wire protocol, port 27017")

Rel_U(updater, rel_db, "Reads from and writes data to", "SQL/JDBC, port 3306")
Rel_U(updater, filesystem, "Writes to")
Rel_U(updater, nosql, "Reads from and writes to", "MongoDB wire protocol, port 27017")

Lay_R(rel_db, filesystem)

SHOW_LEGEND()
@enduml

Custom schema definition

If the custom (color) schema is defined via UpdateElementStyle() then the legend of existing elements is updated too.

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

!$COLOR_A_5 = "#7f3b08"
!$COLOR_A_4 = "#b35806"
!$COLOR_A_3 = "#e08214"
!$COLOR_A_2 = "#fdb863"
!$COLOR_A_1 = "#fee0b6"
!$COLOR_NEUTRAL = "#f7f7f7"
!$COLOR_B_1 = "#d8daeb"
!$COLOR_B_2 = "#b2abd2"
!$COLOR_B_3 = "#8073ac"
!$COLOR_B_4 = "#542788"
!$COLOR_B_5 = "#2d004b"
!$COLOR_REL_LINE = "#8073ac"
!$COLOR_REL_TEXT = "#8073ac"

UpdateElementStyle("person", $bgColor=$COLOR_A_5, $fontColor=$COLOR_NEUTRAL, $borderColor=$COLOR_A_1, $shadowing="true")
UpdateElementStyle("external_person", $bgColor=$COLOR_B_5, $fontColor=$COLOR_NEUTRAL, $borderColor=$COLOR_B_1)
UpdateElementStyle("system", $bgColor=$COLOR_A_4, $fontColor=$COLOR_NEUTRAL, $borderColor=$COLOR_A_2)
UpdateElementStyle("external_system", $bgColor=$COLOR_B_4, $fontColor=$COLOR_NEUTRAL, $borderColor=$COLOR_B_2)
UpdateRelStyle($lineColor=$COLOR_REL_LINE, $textColor=$COLOR_REL_TEXT)

Person(customer, "Personal Banking Customer")
System(banking_system, "Internet Banking System")

System_Ext(mail_system, "E-mail system")
System_Ext(mainframe, "Mainframe Banking System")

Rel(customer, banking_system, "Uses")
Rel_Back(customer, mail_system, "Sends e-mails to")
Rel_Neighbor(banking_system, mail_system, "Sends e-mails")
Rel(banking_system, mainframe, "Uses")

SHOW_LEGEND()
@enduml

Element properties

A model can be extended with (a table of) properties that concrete deployments or more detailed concepts can be documented:

• SetPropertyHeader(col1Name, col2Name, ?col3Name, ?col4Name) The properties table can have up to 4 columns. The default header uses the column names “Name”, “Description”.
• WithoutPropertyHeader() If no header is used, then the second column is bold.
• AddProperty(col1, col2, ?col3, ?col4) (All columns of) a property which will be added to the next element.

Following sample uses all 3 different property definitions (and the aligned deployment node).

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

' default header Property, Value
AddProperty("Name", "Flash")
AddProperty("Organization", "Zootopia")
AddProperty("Tool", "Internet Explorer 7.0")
Person(personAlias, "Label", "Optional Description (with default property header)")

SetPropertyHeader("Property","Value", "Description")
AddProperty("Prop1", "Value1", "Details1")
AddProperty("Prop2", "Value2", "Details2")
Deployment_Node_L(nodeAlias, "Label", "Optional Type", "Optional Description (with custom property header)") {

  WithoutPropertyHeader()
  AddProperty("PropC1", "ValueC1")
  AddProperty("PropC2", "ValueC2")
  Container(containerAlias, "Label", "Technology", "Optional Description (without property header)")
}

System(systemAlias, "Label", "Optional Description (without properties)")

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

Version information

C4-PlantUML offers version information like PlantUML with its %version() call.

• C4Version(): Current C4-PlantUML version (e.g. 2.4.0beta1).
• C4VersionDetails(): (Floating) version details with the current PlantUML and C4-PlantUML version. (It can be referenced via the alias C4VersionDetailsArea.)

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

' existing plantuml version as text
%version()

' new C4-Plantuml version as text 
C4Version()

' new C4-Plantuml version details (incl. PlantUML version) as table
C4VersionDetails()

' version functions used in e.g. footer
footer drawn with PlantUML v. %version() and C4-PlantUML v. C4Version()
@enduml

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.

Live Templates for IntelliJ

Prerequisites

Graphviz download
PlantUML Integration

Install

1. Download IntelliJ live template.
2. Select File | Manage IDE Settings | Import Settings from the IntelliJ IDEA menu.
3. Specify the path to the downloaded ZIP file: c4_live_template.zip.
4. In the Import Settings dialog, select the Live templates checkbox and click OK.
5. Restart IntelliJ.

Usage

• Create new PlantUML file (.puml).
• Type c4_ for displaying artifacts templates for C4-PlantUML
• Live template create correct C4 model artifact with stubbed arguments.
  • E.g. alias, label, type, technology, description
• Replace stubbed arguments with desired values.

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

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