C4 Model Architecture Diagram Code Drawing Practice

Good software architecture diagrams clearly express design intent, help development teams understand system structure, improve communication, identify potential issues, and support future extensions, thereby increasing development efficiency and quality.

The article introduces the C4 model—a simple, well‑defined, developer‑friendly visualisation approach—and walks readers through creating elegant C4 diagrams using code.

1. Introduction to the C4 Model

The C4 model provides four static views: System Context, Container, Component, and Code. It also defines an extended System Landscape view to show how multiple systems interact within an organization.

2. C4 Views Explained

System Context diagram shows the system’s boundaries, users, and external systems without technical details, making it suitable for non‑technical audiences.

Container diagram expands the context by describing deployable units (applications, databases, message queues, etc.) and their responsibilities, technologies, and interactions.

Component diagram zooms into a single container, detailing the internal components, their responsibilities, and technical choices.

Code diagram (optional) depicts low‑level details such as classes or database tables, usually generated from IDEs when needed.

System Landscape diagram places multiple systems together to illustrate overall enterprise relationships.

Dynamic diagram shows runtime interactions and sequence of actions.

Deployment diagram maps containers or systems to physical/virtual nodes (servers, cloud services, etc.) in a given environment.

3. Modelling Guidelines and Checklist

The C4 model provides a set of drawing conventions (titles, legends, clear element types, labels, and technology annotations) and a Review Checklist to ensure diagram readability.

4. Tool Selection for Text‑Based Diagram Generation

Two approaches exist: graphical editors (e.g., draw.io, PowerPoint) and text‑based tools (e.g., PlantUML, Mermaid, Structurizr). The article focuses on the text‑based approach using C4‑PlantUML.

5. Environment Setup

VS Code : install VS Code, add the PlantUML extension, configure code snippets, and install Graphviz for rendering.

IntelliJ IDEA : install the PlantUML Integration plugin and import the provided live‑template ZIP.

6. Example: Recruitment App Container Diagram

The following PlantUML source renders a complete container‑level diagram for a recruitment application.

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml
!define SPRITESURL https://raw.githubusercontent.com/rabelenda/cicon-plantuml-sprites/master/sprites
!define DEVICONS https://raw.githubusercontent.com/tupadr3/plantuml-icon-font-sprites/master/devicons
!define DEVICONS2 https://raw.githubusercontent.com/tupadr3/plantuml-icon-font-sprites/master/devicons2
!define FONTAWESOME https://raw.githubusercontent.com/tupadr3/plantuml-icon-font-sprites/master/font-awesome-5
!include DEVICONS/java.puml
!include DEVICONS/mysql.puml
!include DEVICONS2/spring.puml
!include DEVICONS2/redis.puml
!include DEVICONS2/android.puml
!include DEVICONS2/apple_original.puml

title Recruitment APP Architecture (Container)

Person(P_User, "Job‑seeker App User")
System_Boundary(Boundary_APP, "Recruitment APP System"){
  Container(C_ANDROID, "Android Mobile", "android", "Mobile client", $sprite="android")
  Container(C_IOS, "iOS Mobile", "iOS", "Mobile client", $sprite="apple_original")
  Container(C_GATEWAY, "HTTP Gateway", "Netty", "Auth & protocol conversion", $sprite="java")
  Container(C_GATEWAY_CACHE, "Gateway Cache", "Redis", "Cache auth tokens", $sprite="redis")
  Container(C_BFF, "BFF Gateway", "Spring Boot", "Aggregate backend APIs", $sprite="spring")
  Container(C_CERT, "Real‑Name Service", "Spring Boot", "Internal identity verification", $sprite="spring")
  Container(C_BIZ_1, "Job Service", "Spring Boot", "Publish & search jobs", $sprite="spring")
  Container(C_PAYMENT, "Payment Service", "Spring Boot", "Internal payment handling", $sprite="spring")
  ContainerDb(CDB_MYSQL, "Job DB", "MySQL", "Persist job data", $sprite="mysql")
}
System_Ext(OUT_S_CERT, "External Real‑Name Service")
System_Ext(OUT_S_PAYMENT, "Third‑Party Payment Service")

Rel(P_User, C_ANDROID, "Register, login, submit resume")
Rel(P_User, C_IOS, "Register, login, submit resume")
Rel(C_ANDROID, C_GATEWAY, "Request service", "HTTPS")
Rel(C_IOS, C_GATEWAY, "Request service", "HTTPS")
Rel_L(C_GATEWAY, C_GATEWAY_CACHE, "Read/Write cache", "jedis")
Rel(C_GATEWAY, C_BFF, "HTTP → RPC", "RPC")
Rel(C_GATEWAY, C_BIZ_1, "HTTP → RPC", "RPC")
Rel(C_GATEWAY, C_PAYMENT, "HTTP → RPC", "RPC")
Rel(C_BFF, C_CERT, "Expose API via BFF", "RPC")
Rel(C_BIZ_1, CDB_MYSQL, "Read/Write", "JDBC")
Rel(C_CERT, OUT_S_CERT, "Query identity info", "HTTPS")
Rel(C_PAYMENT, OUT_S_PAYMENT, "Process payment", "HTTPS")
left to right direction
SHOW_LEGEND()
@enduml

The diagram uses icons for technologies (Java, MySQL, Spring, Redis, Android, iOS) and includes a legend for clarity.

7. C4‑PlantUML Syntax Overview

Elements are declared with Container(alias, "label", "technology", "description") , Person , System , System_Ext , etc. Relationships are defined with Rel(from, to, "label", "technology") . Include statements bring in the C4 libraries and icon sets. Layout directives such as left to right direction or LAYOUT_TOP_DOWN() control automatic positioning.

8. Conclusion

The article demonstrates how to adopt the C4 model for architecture visualisation, use C4‑PlantUML to generate diagrams programmatically, and provides practical guidance on tooling, syntax, and best‑practice checklists. Readers are encouraged to explore the official C4 website and the C4‑PlantUML repository for further details.

References: C4 Model: https://c4model.com/ C4‑PlantUML: https://github.com/plantuml-stdlib/C4-PlantUML