Comprehensive Guide: C4 Supplementary Diagrams — Dynamic vs. Sequence Diagrams

A practical comparison for software architects and development teams using the C4 model

📘 Introduction

The C4 model provides a hierarchical approach to visualizing software architecture through four core static structure diagrams: Context, Containers, Components, and Code . However, static diagrams alone cannot fully capture how a system behaves at runtime. This is where the C4 model’s supplementary diagrams—Dynamic and Sequence diagrams—add critical value by illustrating runtime interactions and data flows.

This guide compares these two supplementary diagram types, explains their purpose within the C4 framework, and provides practical guidelines for when and how to use each.

🔍 What Are C4 Dynamic and Sequence Diagrams?

C4 Dynamic Diagram

A Dynamic diagram is based on a UML communication diagram (formerly “collaboration diagram”) and shows how elements in the static model collaborate at runtime to implement a user story, use case, or feature. It uses numbered interactions to indicate ordering and allows a free-form arrangement of diagram element.

Key characteristics:

• Focuses on collaboration patterns rather than strict temporal ordering
• Elements can be positioned for visual clarity, not timeline alignment
• Uses indexed relationships (e.g., Rel($index=1, ...)) to show sequence
• Supports both “collaboration style” (spatial) and “sequence style” (linear) layouts

C4 Sequence Diagram (C4-Styled)

A C4-styled Sequence diagram leverages PlantUML’s native sequence diagram syntax while reusing C4 model elements (Person, Container, Component) as participants. It emphasizes temporal ordering with vertical lifelines and horizontal messages.

Key characteristics:

• Strict top-to-bottom timeline representing message flow over time
• Uses PlantUML sequence syntax (->, -->, activate, deactivate)
• Boundaries defined without {} and closed with Boundary_End()
• Supports C4 styling (colors, sprites, tags) while maintaining sequence semantics

🎯 Purpose: Why Add These to the Standard C4 Model?

💡 Key Insight: These diagrams are supplementary, not replacements. They should be used sparingly to illustrate interesting or recurring patterns that require complicated interactions .

⚖️ Dynamic vs. Sequence: Key Differences

Visual Comparison Using Your Examples

Dynamic Diagram Style (free-form, numbered):
Rel_R(c1, c2, “Submits credentials to”, “JSON/HTTPS”) // Step 1
Rel(c2, c3, “Calls isAuthenticated() on”) // Step 2
Rel_R(c3, c4, “select * from users…”, “JDBC”) // Step 3

Sequence Diagram Style (timeline, lifelines):
c1 -> c2: Submits credentials to [JSON/HTTPS]
activate c2
c2 -> c3: Calls isAuthenticated() on
activate c3
c3 -> c4: select * from users… [JDBC]

🧭 When to Use Which?

✅ Use a Dynamic Diagram when:

• You want to emphasize collaboration patterns over strict timing
• The workflow has parallel or conditional branches that benefit from spatial layout
• You’re documenting a use case for mixed audiences (technical + non-technical)
• You need to overlay the interaction flow directly onto an existing Container/Component diagram
• You prefer free-form positioning to reduce visual clutter

✅ Use a Sequence Diagram when:

• Precise message ordering, activation/deactivation, or return values matter
• You’re modeling synchronous request/response patterns with clear lifecycles
• Your team is already familiar with UML sequence diagrams
• You need to show timeouts, retries, or asynchronous callbacks explicitly
• You’re integrating with PlantUML’s advanced sequence features (loops, alt/else, parallel)

❌ Avoid both when:

• The interaction is trivial (a single request/response)
• The static Container/Component diagram already makes the flow obvious
• You’re creating documentation for executive audiences (use higher-level Context diagrams instead)
• You risk diagram bloat—remember: “dynamic diagrams should be used sparingly”

🛠️ Key Concepts & Implementation Tips

For Dynamic Diagrams (C4_Dynamic.puml)

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Dynamic.puml

LAYOUT_WITH_LEGEND()

ContainerDb(c4, “Database”, “Relational Database Schema”, “Stores user registration information, hashed authentication credentials, access logs, etc.”)
Container(c1, “Single-Page Application”, “JavaScript and Angular”, “Provides all of the Internet banking functionality to customers via their web browser.”)
Container_Boundary(b, “API Application”) {
Component(c3, “Security Component”, “Spring Bean”, “Provides functionality Related to signing in, changing passwords, etc.”)
Component(c2, “Sign In Controller”, “Spring MVC Rest Controller”, “Allows users to sign in to the Internet Banking System.”)
}
Rel_R(c1, c2, “Submits credentials to”, “JSON/HTTPS”)
Rel(c2, c3, “Calls isAuthenticated() on”)
Rel_R(c3, c4, “select * from users where username = ?”, “JDBC”)
@enduml

For Sequence Diagrams (C4_Sequence.puml)

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Sequence.puml

Container(c1, “Single-Page Application”, “JavaScript and Angular”, “Provides all of the Internet banking functionality to customers via their web browser.”)

Container_Boundary(b, “API Application”)
Component(c2, “Sign In Controller”, “Spring MVC Rest Controller”, “Allows users to sign in to the Internet Banking System.”)
Component(c3, “Security Component”, “Spring Bean”, “Provides functionality Related to signing in, changing passwords, etc.”)
Boundary_End()

ContainerDb(c4, “Database”, “Relational Database Schema”, “Stores user registration information, hashed authentication credentials, access logs, etc.”)

Rel(c1, c2, “Submits credentials to”, “JSON/HTTPS”)
Rel(c2, c3, “Calls isAuthenticated() on”)
Rel(c3, c4, “select * from users where username = ?”, “JDBC”)

SHOW_LEGEND()
@enduml

Best Practices for Both

1. Start from static diagrams: Ensure all elements in your dynamic/sequence diagram exist in your Container or Component diagram
2. Limit scope: Focus on one use case, feature, or user journey per diagram
3. Use descriptive labels: Include protocol/technology in relationship labels (e.g., "JSON/HTTPS", "JDBC")
4. Add legends: Use LAYOUT_WITH_LEGEND() or SHOW_LEGEND() for clarity
5. Keep it maintainable: Store diagrams as code (.puml) in version control alongside source code
6. Link to requirements: Reference user stories or ticket IDs in diagram titles or notes

📋 Decision Flowchart

Need to show runtime behavior?
│
├─► Is precise timing/activation critical? ──► Yes ──► Use Sequence Diagram
│                                           │
│                                           └─► No ──► Continue
│
├─► Is spatial layout/clarity more important than timeline? ──► Yes ──► Use Dynamic Diagram
│
├─► Does the workflow have complex branching/parallelism? ──► Yes ──► Prefer Dynamic Diagram
│
├─► Is your team more familiar with UML sequences? ──► Yes ──► Use Sequence Diagram
│
└─► Default recommendation: Start with Dynamic Diagram (more C4-native, flexible)

🏁 Conclusion

Both C4 Dynamic and Sequence diagrams serve the same fundamental purpose: making runtime behavior visible within the C4 model’s static architecture framework. The choice between them isn’t about which is “better,” but which better serves your audience, use case, and team workflow.

• Dynamic diagrams excel at showing collaboration patterns with flexible layout—ideal for documentation, onboarding, and cross-functional communication.
• Sequence diagrams excel at showing precise temporal behavior—ideal for technical design reviews, debugging complex flows, or teams steeped in UML.

🎯 Final Recommendation: Start with a Dynamic diagram for most use cases. Only reach for a Sequence diagram when you genuinely need PlantUML’s advanced sequence features or your team requires strict temporal semantics. And always remember: diagrams are communication tools, not artifacts for their own sake .

📚 References & Resources

1. C4 Model: Dynamic Diagram
2. C4-PlantUML Documentation
3. C4 Model Introduction
4. C4-PlantUML Samples on GitHub
5. Online C4 Model Software: Visual Paradigm’s online C4 Model software makes C4 Model creation fast and straight-forward.
6. C4 Model Diagrams Visual Paradigm Desktop: supports complete C4 Model diagramming with six essential diagram types.
7. The Ultimate Guide to C4-PlantUML Studio: Step-by-step workflows for creating, refining, and sharing diagrams
8. Beginner’s Guide to C4 Model Diagrams