Basic support for C4 model primitives.

[mbruggmann]

C4 is a model for visualizing software architecture. It defines a common terminology and a few core diagrams at different abstraction levels. We primarily use the System Landscape, System Context and Container diagrams so I started with just the entities needed for those.

For a definition like this:

from diagrams import Diagram
from diagrams.c4 import Person, Container, Database, System, SystemBoundary, Relationship

graph_attr = {
    "splines": "spline",
}

with Diagram("Container diagram for Internet Banking System", direction="TB", graph_attr=graph_attr):
    customer = Person(
        name="Personal Banking Customer", description="A customer of the bank, with personal bank accounts."
    )

    with SystemBoundary("Internet Banking System"):
        webapp = Container(
            name="Web Application",
            technology="Java and Spring MVC",
            description="Delivers the static content and the Internet banking single page application.",
        )

        spa = Container(
            name="Single-Page Application",
            technology="Javascript and Angular",
            description="Provides all of the Internet banking functionality to customers via their web browser.",
        )

        mobileapp = Container(
            name="Mobile App",
            technology="Xamarin",
            description="Provides a limited subset of the Internet banking functionality to customers via their mobile device.",
        )

        api = Container(
            name="API Application",
            technology="Java and Spring MVC",
            description="Provides Internet banking functionality via a JSON/HTTPS API.",
        )

        database = Database(
            name="Database",
            technology="Oracle Database Schema",
            description="Stores user registration information, hashed authentication credentials, access logs, etc.",
        )

    email = System(name="E-mail System", description="The internal Microsoft Exchange e-mail system.", external=True)

    mainframe = System(
        name="Mainframe Banking System",
        description="Stores all of the core banking information about customers, accounts, transactions, etc.",
        external=True,
    )

    customer >> Relationship("Visits bigbank.com/ib using [HTTPS]") >> webapp
    customer >> Relationship("Views account balances, and makes payments using") >> [spa, mobileapp]
    webapp >> Relationship("Delivers to the customer's web browser") >> spa
    spa >> Relationship("Make API calls to [JSON/HTTPS]") >> api
    mobileapp >> Relationship("Make API calls to [JSON/HTTPS]") >> api

    api >> Relationship("reads from and writes to") >> database
    api >> Relationship("Sends email using [SMTP]") >> email
    api >> Relationship("Makes API calls to [XML/HTTPS]") >> mainframe
    customer << Relationship("Sends e-mails to") << email

It produces a diagram like this:

The implementation is a bit different from the other resources which are auto-generated based on images as far as I understand. If you'd prefer a different approach or would rather not have this upstream in diagrams, let me know! I also wasn't sure how to best integrate this in the documentation, but we could figure something out if this is a feature you'd like to see.

Original discussion in #489.

[mbruggmann]

@mingrammer Any thoughts on this?

[gabriel-tessier]

@mbruggmann
It's a good start I can help to add more feature and documentation but I still want to wait if @mingrammer is interested to add it in diagrams.
I also checked about C4 website and I think that is better to confirm that we can implement (i.e feasibility) more feature before adding any C4 support, otherwise we will have a poor implementation.
Maybe we can start by listing what can be done and a roadmap!
If it's not merged in this lib we can always start a fork! 😀

[BBartosz]

Would be great to see c4 support in diagrams. @mbruggmann implementation looks promising, it has everything what is important

[BBartosz]

@mbruggmann I dont know diagrams capabilities much but is it possible to make those components clickable and animated? So lets say you have your internet banking system as system boundary, one box. You double click it and it expands to more granular version like we see on screenshot you attached?

[clayms]

@BBartosz have a look at https://graphviz.org/doc/info/attrs.html#d:URL

[clayms]

@BBartosz I don't know of any native animation capability in graphviz or the wrapper libraries. Have a look at this library which uses d3 to animate https://github.com/magjac/d3-graphviz#examples

I have not tested, but it looks like to create your graphs with this library, save the dot files, then use the magjac/d3-graphviz animation library on the dot files.

[mbruggmann]

@BBartosz What we do is roughly like this:

• Have an internal website where we host diagram pages
• Diagram pages follow a known URL scheme to address each system/container/..., like my.internal.website/diagrams/container-id
• Use the URL or href attributes in the diagram to create links to other pages, eg diagrams.c4.Container(..., href='my.internal.website/diagrams/container-id')
• Render the diagrams to svg to retain the links

Currently this is set up using PlantUML but I don't see a reason why it wouldn't work using diagrams in a similar fashion. I haven't tried though.

[BBartosz]

@mbruggmann Thats also possibility. Just have CI to generate graphs and put them into static page manually/have a script to do this. Something similar is done here: https://adrianvlupu.github.io/C4-Builder/#/?id=overview

[mingrammer]

Great. I'll review this feature soon.

[dineshdh]

@mingrammer are you able to review this. I would love to see this feature asap

[venthur]

Is the "view" part strictly separated from the "model"? I.e. can you create exactly one model and derive different views from that?

[mbruggmann]

@venthur At the moment, no. The suggested implementation is purely about rendering one view. So if you wanted to model entities/relationships, you'd need to do that outside of diagrams and just use this in the rendering path.

[jonesy1234]

@mingrammer Any way we can help get this PR over the line as would love to use this natively?

[kaimallea]

Looking forward to this feature! I just bought @mingrammer 5 coffees. Maybe a little caffeine is all that's needed to help get this across the finish line. 😉

[mingrammer]

I'll review this feature this week!! Sorry for the really late review.

[kupolak]

Hi @mingrammer, any chance to review and merge it soon? 😄 It would be awesome!

[mingrammer]

LGTM. Sorry for the really late review. Thanks for the great contributions! ❤️

But, I have the last suggestion. Could you please add the documentation for C4 model support to diagrams docs, and update the README?

[mbruggmann]

@mingrammer Cool, no worries. Documentation added!

[mingrammer]

LGTM! Thank you for great contributing!

[mingrammer]

I'm on work time. I'll release the new version tomorrow morning. (KST)

[mingrammer]

diagrams@v0.22.0 is now released.