Add C4 Diagram. Compatible with C4-PlantUML syntax.

[pinghe]

#1276

feat: Add C4 Diagram. Compatible with C4-PlantUML syntax

    C4Context
      title System Context diagram for Internet Banking System

      Person(customerA, "Banking Customer A", "A customer of the bank, with personal bank accounts.")
      Person(customerB, "Banking Customer B")
      Person_Ext(customerC, "Banking Customer C")
      System(SystemAA, "Internet Banking System", "Allows customers to view information about their bank accounts, and make payments.")

      Person(customerD, "Banking Customer D", "A customer of the bank, <br/> with personal bank accounts.")

      Enterprise_Boundary(b1, "BankBoundary") {

        SystemDb_Ext(SystemE, "Mainframe Banking System", "Stores all of the core banking information about customers, accounts, transactions, etc.")

        System_Boundary(b2, "BankBoundary2") {
          System(SystemA, "Banking System A")
          System(SystemB, "Banking System B", "A system of the bank, with personal bank accounts.")
        }

        System_Ext(SystemC, "E-mail system", "The internal Microsoft Exchange e-mail system.")
        SystemDb(SystemD, "Banking System D Database", "A system of the bank, with personal bank accounts.")

        Boundary(b3, "BankBoundary3", "boundary") {
          SystemQueue(SystemF, "Banking System F Queue", "A system of the bank, with personal bank accounts.")
          SystemQueue_Ext(SystemG, "Banking System G Queue", "A system of the bank, with personal bank accounts.")
        }
      }

      BiRel(customerA, SystemAA, "Uses")
      BiRel(SystemAA, SystemE, "Uses")
      Rel(SystemAA, SystemC, "Sends e-mails", "SMTP")
      Rel(SystemC, customerA, "Sends e-mails to")

📑 Summary

feat: Mermaid includes c4 for creating C4 diagrams. Compatible with C4-PlantUML syntax.

The layout does not use a fully automated layout algorithm. The position of shapes is adjusted by changing the order in which statements are written. So there is no plan to support the following Layout statements.

• Layout
• • Lay_U, Lay_Up
• • Lay_D, Lay_Down
• • Lay_L, Lay_Left
• • Lay_R, Lay_Right

The following statements are not supported in the short term.

• sprite
• tags
• link
• Legend

TODO:

• System Context

• • 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 diagram

• • Container(alias, label, ?techn, ?descr, ?sprite, ?tags, $link)
• • ContainerDb
• • ContainerQueue
• • Container_Ext
• • ContainerDb_Ext
• • ContainerQueue_Ext
• • Container_Boundary(alias, label, ?tags, $link)

• Component diagram

• • Component(alias, label, ?techn, ?descr, ?sprite, ?tags, $link)
• • ComponentDb
• • ComponentQueue
• • Component_Ext
• • ComponentDb_Ext
• • ComponentQueue_Ext

• Dynamic diagram

• • RelIndex(index, from, to, label, ?tags, $link)

• Deployment diagram

• • Deployment_Node(alias, label, ?type, ?descr, ?sprite, ?tags, $link)
• • Node(alias, label, ?type, ?descr, ?sprite, ?tags, $link): short name of Deployment_Node()
• • Node_L(alias, label, ?type, ?descr, ?sprite, ?tags, $link): left aligned Node()
• • Node_R(alias, label, ?type, ?descr, ?sprite, ?tags, $link): right aligned Node()

• Relationship Types

• • Rel(from, to, label, ?techn, ?descr, ?sprite, ?tags, $link)
• • BiRel (bidirectional relationship)
• • Rel_U, Rel_Up
• • Rel_D, Rel_Down
• • Rel_L, Rel_Left
• • Rel_R, Rel_Right
• • Rel_Back
• • RelIndex * Compatible with C4-Plantuml syntax, but ignores the index parameter. The sequence number is determined by the order in which the rel statements are written.

📋 Tasks

Make sure you

• 📖 have read the contribution guidelines
• 💻 have added unit/e2e tests (if appropriate)
• 🔖 targeted develop branch

[pinghe]

[knsv]

@pinghe This looks fantastic!

There only some parts missing in order to move this all the way to being finished!

Whats missing is a few things that we try to keep common between diagrams like theming support etc. You can find more details in common-parts of a diagram section in the docs

[geshan]

is this getting merged anytime soon?

[knsv]

Merging, will be classed as experimental until we support the remaining parts. Thanks @pinghe

[geshan]

Are there any docs on how to use it, tried it on gist, and did not work. Came back with the following error:

Error rendering embedded code

Parse error on line 1:
C4Context titl
^
Expecting 'open_directive', 'NEWLINE', 'SPACE', 'GRAPH', got 'ALPHA'

For more information, see https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams#creating-mermaid-diagrams

[SeidChr]

Are there any docs on how to use it, tried it on gist, and did not work. Came back with the following error:

Looking at the merged pr, it seems to be started with "c4"
a1ef3f0#diff-2c86258ec964ee09ea541b1287ac89c257580210a01465f2a719bb57c2ec7c29R55

[numbsafari]

It doesn't look like this version has rolled out to the GitHub integration yet. Anyone reading this able to find any indication from GitHub what their policy is for accepting updates from the upstream project? I haven't been able to find that information yet.

This would be a great feature to include in, e.g., ARCHITECTURE.md files.

[pinghe]

@geshan geshan
Line break required between 'C4Context title'.

https://mermaid-js.github.io/mermaid/#/c4c

[pinghe]

@knsv
C4 diagram is fixed style, such as css color, so different css is not provided under different skins.

I will commit a new PR( #3151 ). The following feature has been added:

updateElementStyle and UpdateElementStyle are written in the diagram last part. updateElementStyle is inconsistent with the original definition and updates the style of the relationship, including the offset of the text label relative to the original position.

• Custom tags/stereotypes support and skinparam updates
• • 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(from, to, textColor, lineColor, ?offsetX, ?offsetY): This call updates the default relationship colors and creates no additional legend entry. Two new parameters, offsetX and offsetY, are added to set the offset of the original position of the text.
• • UpdateLayoutConfig(?c4ShapeInRow, ?c4BoundaryInRow): New. This call updates the default c4ShapeInRow(4) and c4BoundaryInRow(2).