Modeling Runtime Behavior

Using Dynamic Diagrams for high-level workflows and message exchanges

While most C4 diagrams focus on static structure (what elements exist and how they are related), the Dynamic Diagram (one of the three supporting views) shifts the perspective to runtime behavior — showing how those elements interact over time to accomplish a specific use case, scenario, or business process.

This view is particularly valuable when static diagrams alone don’t tell the full story: when you need to explain sequences, message flows, event triggers, asynchronous processing, error paths, or cross-system collaboration in a clear, visual way.

Purpose of Dynamic Diagrams

Dynamic Diagrams help answer questions like:

• What actually happens step-by-step when a customer places an order?
• How does an event flow through the system to update multiple services?
• Where are the key decision points, synchronous calls, or asynchronous notifications?
• How do external systems participate in a critical business workflow?
• What messages are exchanged during authentication, payment processing, or order fulfillment?
• Where might latency, failures, or race conditions occur?

They are scenario-specific — you create one Dynamic Diagram per important use case or workflow (not one giant diagram for everything).

Key Characteristics

• Lightweight and simplified — use the same C4 element types (Persons, Software Systems, Containers, or even Components) but focus on sequence and timing rather than exhaustive structure.
• Similar to UML sequence/collaboration diagrams — but without strict UML notation, lifelines, activation bars, or complex fragments. The C4 approach keeps it simple: boxes + arrows + numbered steps.
• High-level — show interactions at the appropriate zoom level (usually Containers or Components, rarely Code). Avoid low-level details like HTTP headers, SQL queries, or exact payloads unless critical.

How to Create a Dynamic Diagram

1. Choose a specific scenario
   • Example: “Customer places an online order”
   • Example: “User logs in via SSO and views account balance”
   • Example: “Order paid → inventory updated → shipping label generated → customer notified”
2. Select the right level of zoom
   • Most common: Container level (shows services, databases, queues interacting)
   • Sometimes: Component level (inside one complex service)
   • Rarely: Mix of Person + Containers + Components for end-to-end flows
3. Lay out participants
   • Place actors (Persons) and systems/containers/components as boxes across the top or left side.
   • Order them logically (e.g., user on left, external systems on right, internal services in the middle).
4. Draw numbered interaction arrows
   • Use solid arrows for synchronous calls (request-response).
   • Use dashed arrows for asynchronous messages/events (fire-and-forget, pub/sub).
   • Number each step sequentially (1, 2, 3…) to show order.
   • Label arrows with:
     • Action/verb (e.g., “POST /orders”, “Publish OrderPlaced”, “Authorize payment”)
     • Optional protocol or payload summary (e.g., “HTTPS/JSON”, “Kafka event”, “Webhook callback”)
5. Include key branches or notes (optional)
   • Add parallel arrows for concurrent actions.
   • Use notes or alt/loop boxes (lightly) for conditions, retries, or error paths.
   • Keep it readable — don’t overload with every possible path.

Common Patterns You’ll Model

• Synchronous request-response (API calls)
• Event-driven flows (publish/subscribe via Kafka, RabbitMQ)
• Callback/webhook patterns (payment confirmation → update order status)
• Orchestration vs. choreography (central orchestrator vs. decentralized events)
• External system hand-offs (e.g., user → app → payment gateway → app callback)
• Human-in-the-loop steps (e.g., approval workflows)

Example Dynamic Diagram

When to Use Dynamic Diagrams

• Onboarding: Explain how the system works for key business processes
• Documentation: Capture critical workflows that static diagrams miss
• Debugging & incident response: Visualize what should happen vs. what did
• Architecture reviews: Assess coupling, latency risks, or resilience
• Security threat modeling: Identify trust boundaries in runtime flows
• API design & contract testing: Show message exchanges between services

Best Practices & Pitfalls to Avoid

• One diagram per scenario — don’t try to show everything in one view
• Number steps clearly and keep sequences linear/readable
• Use consistent arrow styles (solid = sync, dashed = async)
• Limit to 10–15 steps maximum — split complex flows into multiple diagrams
• Avoid code-level detail (no stack traces, no exact JSON)
• Prefer PlantUML, Structurizr, or Mermaid for versionable, text-based dynamic diagrams

Dynamic Diagrams bring your architecture to life by showing motion and behavior — turning a static blueprint into a story of how the system actually delivers value in real time.

In the hands-on section ahead, you’ll select key scenarios from previous examples (e.g., order placement, user authentication), model their runtime interactions at container or component level, and use tools to generate clean, numbered sequence views that make complex workflows instantly understandable.

This supporting view is often the one that makes architecture documentation feel truly alive and useful to both developers and business stakeholders.