C4 model: Container diagrams

简介 / Introduction

The C4 model provides a layered approach to describing software architecture — Context, Container, Component, and Code — with Container diagrams focusing on the key application processes and data stores inside a system’s boundary. This article renders the same Container diagram using both PlantUML (stdlib) and Mermaid (built-in C4 extension).

PlantUML 版

PlantUML uses !include <C4> to load the C4 stdlib, declares containers with Container(...), uses ContainerDb for data stores, and System_Boundary to group components:

!include <C4/C4_Container>
!include <C4/C4_Context>

Person(customer, "Customer", "Uses web browser or mobile app")
System_Boundary(system, "E-commerce System") {
    Container(spa, "Web Frontend", "Angular/SPA", "Product browsing and order UI")
    Container(api, "API Service", "Spring Boot", "Business logic")
    ContainerDb(db, "Primary DB", "PostgreSQL", "Orders, products, users")
    Container(cache, "Cache", "Redis", "Hot data cache")
}
System_Ext(pay, "Payment Gateway", "Third-party payment")
System_Ext(mail, "Mail Service", "SMTP email delivery")

Rel(customer, spa, "Browse & Order", "HTTPS")
Rel(spa, api, "REST API calls", "JSON/HTTPS")
Rel(api, db, "Read/write", "JDBC")
Rel(api, cache, "Cache R/W", "Redis protocol")
Rel(api, pay, "Initiate payment", "HTTPS")
Rel(api, mail, "Send confirmation", "SMTP")
ShowContainerLayout

Mermaid 版

Mermaid’s C4 syntax uses the c4Context diagram type with Container/ContainerDb/System nodes:

c4Context
    title C4 Container diagram for E-commerce System
    Container(spa, "Web Frontend", "Angular/SPA", "Product browsing and order UI")
    Container(api, "API Service", "Spring Boot", "Business logic")
    ContainerDb(db, "Primary DB", "PostgreSQL", "Orders, products, users")
    Container(cache, "Cache", "Redis", "Hot data cache")
    System_Boundary(system, "E-commerce System Boundary")
    System(pay, "Payment Gateway")
    System(mail, "Mail Service")
    System(customer, "Customer")

    Rel(customer, spa, "Browse & Order")
    Rel(spa, api, "REST API calls")
    Rel(api, db, "Read/write")
    Rel(api, cache, "Cache R/W")
    Rel(api, pay, "Initiate payment")
    Rel(api, mail, "Send confirmation")

对比 / Side-by-side

Feature	PlantUML	Mermaid
Diagram type declaration	`!include <C4/C4_Container>` + diagram type	`c4Context`
Container node	`Container(id, name, tech, desc)`	`Container(id, name, tech, desc)`
Database node	`ContainerDb(id, name, tech, desc)`	`ContainerDb(id, name, tech, desc)`
System boundary	`System_Boundary(name) { ... }`	`System_Boundary(name)`
External system	`System(name, desc)`	`System(name, desc)`
Relationship arrow	`Rel(source, target, label)`	`Rel(source, target, label)`
Stdlib required	Yes (`plantuml-stdlib`)	No (C4 built into Mermaid)

小结 / Wrap-up

PlantUML’s C4 stdlib is semantically complete and feature-rich, ideal for formal architecture documentation that strictly follows the C4 spec — but it requires the stdlib to be installed on the backend. Mermaid ships C4 syntax natively, making it frictionless for quick prototypes and internal docs. Both export to SVG; when embedding in Confluence or Notion, consider injecting xmlns:xlink to ensure images render correctly.