C4Model Diagrams

[tjdavis3]

Currently I use PlantUML for most of my diagrams along with C4-PlantUML to do C4Model. I've been playing around with d2 and feel the syntax is somewhat better than PlantUML, however, I cannot find a clean way to create C4Model diagrams. I can kind of do it with nested icons and markdown, but it's kind of kludgy and doesn't look anywhere near as clean as C4-PlantUML diagrams.

It would be nice if there were a way to create an object with:

• type (system, container, component)
• technology
• description
• icon (optional)

And have it render as a single component. A simple C4 diagram would looks something like this:

[jameschensmith]

This would be so great to have out-of-the-box. I went ahead and attempted a C4 diagram based on the image in OP to get an idea of what the code would look like if you wanted to create a C4 model diagram today. You can find it below.

One thing I couldn't solve was expanding the "Sample System" container so that the type was not hidden behind the "Web Application" container. Also, the HTML is not necessary if you don't mind the content not being centered. You could also just use the label in this place, but the whole content would be bold, italic, underline, etc. depending on how you style it (i.e., you wouldn't be able to style each part individually when using a label).

C4 model diagram in D2

Admin: "" {
  text: |md
    <p align="center">
      <strong>Administrator</strong><br />
      [Person]
    </p>
  |
}

Sample System: "Sample System\n[System]" {
  style: {
    stroke-dash: 3
  }

  Web App: "" {
    text: |md
      <p align="center">
        <strong>Web Application</strong><br />
        [Container: C#, ASP.NET Core 2.1 MVC]<br />
        Allows users to compare multiple Twitter timelines
      </p>
    |
  }
}

Twitter: "" {
  text: |md
    <p align="center">
      <strong>Twitter</strong><br />
      [Software System]
    </p>
  |
}

Admin -> Sample System.Web App: "Uses\n[HTTPS]"
Sample System.Web App -> Twitter: "Gets tweets from\n[HTTPS]"

— Playground Link

Exported SVG & PNG

[jameschensmith]

Perhaps what we could do is submit a C4 diagram to the text-to-diagram site. Stated in the README is the following (added bold to the place to draw focus to):

Full disclosure: This is created and maintained by Terrastruct. We created D2, and it's in our interest to provide anyone evaluating us with an objective comparison against alternatives. The only favor granted to D2 is that it shows up as the first comparison. We welcome contributions. Even ones that make D2 look bad (it'll be motivation for us to patch it!).

We would need an example for the other text-to-diagram tools.

[alixander]

Sounds good. AFAIK, only plantuml would have it right? (via their plantuml-c4 extension)

[jameschensmith]

You may be right. Though, I do see Mermaid may have experimental support as well. When initially submitted to text-to-diagram, could we initially set the other tools to not supported until another contributor submits an example from one of the tools? Not sure if all the examples would be needed for an initial submission 🤔 💭

[alixander]

just as an update, the work for this is merged: (the layers part of this PR) #714

we'll be writing docs and cut a release over the coming week

[tjdavis3]

Here's the plantuml code for the OP diagram

@startuml Basic Sample
!include <c4/C4_Container>

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

[ChrisNeff]

Can we get a C4 theme example and a few of the C4 icons added to the icons site?

[alixander]

Yes, will do

[alixander]

I'll be dedicating some time to support C4 diagrams in D2 in the coming days.

Tracking list of TODOs. Once these are done, C4 diagrams should be fully supported. If someone looks through this and thinks there's something missing, please let me know.

• class shape, add "stereotype" #1081
• https://github.com/terrastruct/src/issues/3664
• add c4 icons to icons.terrastruct.com #2163
• write c4 use case docs d2-docs#237
• reference objects in layers #2164
• spread current file objects #2165