RFC: c4-beta - a modern, Structurizr-inspired C4 diagram type

[filipsajdak]

Motivation

The current C4 diagram is experimental, uses a hand-rolled row-based layout (no real layout algorithm), and its C4-PlantUML macro syntax (Person(alias, "label", ...)) is verbose and error-prone. Issues #7492, #7358, #4906 and discussion #4522 document the pain. In parallel to the unified-renderer migration for the existing syntax (#7673, first slice #7842), we propose a new diagram type with a clean, mermaid-idiomatic syntax modeled on the Structurizr DSL.

This design has been reviewed by Simon Brown (@simonbrowndotje), the creator of the C4 model and Structurizr, in the comments below. The syntax now reflects his guidance.

Proposed syntax

c4-beta container
title Internet Banking System - Containers
direction TB

person customer "Personal Banking Customer" "A customer of the bank."
softwareSystem banking "Internet Banking System" {
    container spa "Single-Page Application" "Provides banking functionality." "JavaScript/Angular"
    container api "API Application" "Provides a JSON/HTTPS API." "Java/Spring MVC"
    container db "Database" "Stores credentials." "Oracle 12c" :::database
}
softwareSystem mainframe "Mainframe Banking System" :::external

customer --> spa : "Uses" "HTTPS"
spa --> api : "Makes API calls to" "JSON/HTTPS"
api --> db : "Reads from and writes to" "SQL/TCP"
api --> mainframe : "Makes API calls to" "XML/HTTPS"

Deployment diagrams add deploymentNode (nestable, with instance counts), infrastructureNode (DNS, load balancers, firewalls), and inline container declarations:

c4-beta deployment
deploymentNode aws "Amazon Web Services" "" "AWS Cloud" {
    infrastructureNode lb "Load Balancer" "" "Elastic Load Balancer"
    deploymentNode ec2 "EC2" "" "Ubuntu 22.04" instances 4 {
        container api "API Application" "" "Java/Spring MVC"
    }
}
lb --> api : "Forwards requests to"

Design principles

• WYSIWYG, one code block = one diagram (no Structurizr workspace/views split). Nesting implies boundary rendering: a softwareSystem with a {} body renders as a boundary; a leaf renders as a box. The same element naturally appears at the right zoom level per diagram.
• Header c4-beta + kind (context|container|component|dynamic|deployment). The kind drives validation and the legend caption, not the grammar.
• Explicit element keywords (per Simon's feedback): person, softwareSystem, container, component, deploymentNode, infrastructureNode, plus group for boundaries. No short system/node aliases - node is overloaded and softwareSystem stays unambiguous if hardware systems ever appear. Elements render their proper C4 type (e.g. <>).
• String order "Name" "Description" "Technology"; technology is honored only on container/component/deploymentNode/infrastructureNode - a software system / person is a black box (per the C4 abstractions).
• Relationships are unidirectional and specifically labelled (C4 guidance): --> / <--; <--> exists as a discouraged shorthand for two relationships. Inter-container relationships carry a technology/protocol.
• Styling is tag-based (CSS-inspired), like Structurizr: :::tag + style <tag> key:value, .... external is not a keyword - it is a conventional :::external tag that ships an overridable default grey style (Simon removed external from Structurizr because it requires a point of reference; tags avoid that).
• Fixed C4 abstractions only - no LikeC4-style arbitrary abstraction levels. Any future extensibility would follow Structurizr's archetype route (still the core abstractions).
• Dynamic diagrams number interactions; repeated step numbers mark parallel interactions (Structurizr's explicit form).
• Auto-generated legend, on by default (c4model.com mandates a key/legend).
• Implemented with a langium grammar (packages/parser) and the unified renderer - dagre by default, ELK via @mermaid-js/layout-elk.

Design decisions confirmed with Simon Brown

• Drop the external keyword; use a conventional :::external tag with an overridable default style (the tags-and-tagging route from Structurizr).
• Explicit softwareSystem/deploymentNode keywords (avoid the overloaded node; stay unambiguous vs hardware systems).
• Technology only on container/component/deployment elements.
• infrastructureNode + deployment-node instance counts are essential to reproduce the canonical Live deployment example - now implemented.
• Stick to the fixed C4 abstractions (option 1), never arbitrary abstractions.

Status

Working prototype: draft PR #7843 - langium grammar, db with getData() -> LayoutData, unified renderer, all five C4 kinds (context, container, component, dynamic, deployment), tag-based styling, the C4 person shape, infrastructureNode + instance counts, and the reproduced Live deployment example. Tracker: #7849.

The legacy C4 syntax remains untouched and fully supported; c4-beta is purely additive (like architecture-beta).

Full disclosure: this proposal and prototype were prepared with assistance from Claude Code; all changes were reviewed and tested by a human.

[filipsajdak]

Update: the prototype in #7843 now implements the complete proposal - all five diagram kinds work end to end (context, container, component, dynamic with numbered steps, deployment with nested nodes), plus the style <tag> key:value statement, :::tag styling, the C4 person shape and kind validation.

Remaining from the proposal (in preparation as separate follow-ups): auto-generated legend (on by default, legend off opt-out), config schema, theme-variable integration, and grammar polish (e.g. allowing element keywords as IDs). Feedback on the syntax is very welcome before we finalize those.

[simonbrowndotje]

Do you need the external keyword? I removed this concept from the Structurizr tooling a few years ago because something being "external" requires a point of reference (i.e. "is this external to the software system, team, organisation, etc?") and was a constant source of confusion ... you'll find comments about this on the C4-PlantUML repo too (example).

[filipsajdak]

Thanks @simonbrowndotje, that is really helpful coming from you, and you are right. It also matches the direction c4-beta already leans: styling is tag-based (:::tag plus style <tag> ..., CSS-inspired). We will drop the external keyword and make external simply a conventional tag that ships with a default, overridable style - the same tags-and-tagging route you took in Structurizr. That removes the privileged keyword and the need for a parallel _Ext variant of every element shape.

(For backward compatibility the legacy C4Context / System_Ext syntax stays unchanged in its own renderer; this applies only to the new c4-beta syntax.)

If you have any other thoughts on the syntax we would genuinely welcome them - thanks again for taking the time to look.

[filipsajdak]

And while we have your attention, a few design questions we would genuinely value your view on for c4-beta (no pressure):

1. Naming: we currently use short system/node keywords and plan to also accept the precise softwareSystem/deploymentNode as canonical aliases. Do you have a preference - is the short form acceptable, or would you steer a new C4 syntax to the full names only?
2. Deployment: for v1 we model nestable deployment nodes with containers inside. Would you consider infrastructureNode (load balancers, firewalls, ...) and explicit container/system instances essential, or reasonable to defer to a follow-up?
3. Extensible vocabulary: we saw your work on archetypes. For a new C4 syntax, would you lean towards exposing user-defined types/archetypes, or keeping strictly to the four fixed abstractions?

Thanks again - your input genuinely shapes this.

[simonbrowndotje]

Naming: we currently use short system/node keywords and plan to also accept the precise softwareSystem/deploymentNode as canonical aliases. Do you have a preference - is the short form acceptable, or would you steer a new C4 syntax to the full names only?

I like being explicit to avoid confusion.

• node is a reasonably overloaded term, so I'd probably steer away from that.
• system is okay, but it depends whether you intend to support hardware systems in the future (example).

Deployment: for v1 we model nestable deployment nodes with containers inside. Would you consider infrastructureNode (load balancers, firewalls, ...) and explicit container/system instances essential, or reasonable to defer to a follow-up?

Essential, otherwise you can't reproduce the new example deployment diagram with its DNS names, load balancers, etc. This same example is also published in my O'Reilly book that will be available imminently.

Extensible vocabulary: we saw your work on archetypes. For a new C4 syntax, would you lean towards exposing user-defined types/archetypes, or keeping strictly to the four fixed abstractions?

You have three options here:

1. Support the C4 abstractions only.
2. Support user-defined archetypes based upon the C4 abstractions (this is what Structurizr does).
3. Support user-defined abstractions (this is what LikeC4 does).

If you're making a C4 tool, you should stick with the defined abstraction levels. LikeC4 provides a mechanism for users to create whatever abstractions they like, which deviates from the C4 model and runs the risk of allowing teams to get into exactly the same problems that C4 was designed to solve - see Can we add more abstraction levels? for more details on this.

Structurizr's archetypes feature provides a way for teams to build their own domain specific language on top of the Structurizr DSL, but any archetypes created are still the core C4 abstractions.

[filipsajdak]

Thank you, this is incredibly useful (and congratulations on the book!). Acting on all three:

• Naming: we will go fully explicit - softwareSystem and deploymentNode as the keywords (dropping the short forms), with proper C4 type labels. Agreed node is overloaded, and softwareSystem keeps us unambiguous if hardware systems ever come up.
• Deployment: we will add infrastructureNode and instance counts (including ranges like 1..N) so the Live deployment example is reproducible - wired up as a worked example/test.
• Abstractions: we will stick to the fixed C4 abstractions (your option 1); any future extensibility would be the archetype route (still the core abstractions), never arbitrary LikeC4-style levels - your FAQ on extra levels makes the case well.

Thanks again - this has materially improved the design.