Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add C4 Diagram. Compatible with C4-PlantUML syntax. #3038

Merged
merged 7 commits into from Jun 7, 2022

Conversation

pinghe
Copy link
Contributor

@pinghe pinghe commented May 15, 2022

#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

```
    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")
```
```
    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")
```
@pinghe
Copy link
Contributor Author

pinghe commented May 15, 2022

image

@pinghe pinghe changed the title Add C4Context diagram. Compatible with C4-PlantUML syntax. Add C4 Diagram. Compatible with C4-PlantUML syntax. May 17, 2022
@knsv
Copy link
Collaborator

knsv commented May 24, 2022

@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
Copy link

geshan commented Jun 6, 2022

is this getting merged anytime soon?

@knsv
Copy link
Collaborator

knsv commented Jun 7, 2022

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

@knsv knsv merged commit 3300ad0 into mermaid-js:develop Jun 7, 2022
8 checks passed
@geshan
Copy link

geshan commented Jun 7, 2022

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
Copy link

SeidChr commented Jun 16, 2022

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
Copy link

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
Copy link
Contributor Author

pinghe commented Jun 18, 2022

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

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

@pinghe
Copy link
Contributor Author

pinghe commented Jun 18, 2022

@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).

ashishjain0512 added a commit that referenced this pull request Jun 28, 2022
Add C4 Diagram. Compatible with C4-PlantUML syntax (2). #3038
@GavinPen GavinPen mentioned this pull request Jul 15, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

5 participants