by Guillermo Quiros
A practical guide to C4 Dynamic diagrams — the tool for showing how elements collaborate at runtime without leaving the C4 notation.
Need the broader model first? Visit the C4 model hub and return here for the Dynamic diagram deep dive.
What Is a C4 Dynamic Diagram?
A **C4 dynamic diagram** shows the runtime behaviour of a set of elements from a static C4 diagram. It is not a new type of element — it reuses the boxes and relationships already defined in your Context, Container, or Component diagrams and adds numbered interaction steps to show how those elements collaborate during a specific flow.
The key insight is that dynamic diagrams are always anchored to a static diagram. You pick a slice of your Context, Container, or Component diagram, then show how the elements in that slice interact to handle a particular scenario — a user login, a payment checkout, an event processing pipeline, a cache warm-up.
Why Dynamic Diagrams Exist
Static C4 diagrams are excellent for describing structure. They answer "what exists and how is it organised?" Dynamic diagrams answer a different question: "what happens when X occurs?"
Without dynamic diagrams, teams usually fall back on two alternatives:
Sequence diagrams (UML style) are detailed and precise but require a different notation and a different toolchain from the rest of the C4 model. They also operate at the message level, which is often lower than what you need for an architecture conversation.
Narrative documentation describes a flow in prose but lacks the visual ordering that makes complex interactions easy to trace.
The C4 dynamic diagram sits between these two. It preserves the abstraction level you chose for the static diagram, adds ordering, and stays within the C4 notation — so readers do not need to switch mental models when they move from the structural view to the runtime view.
Elements of a Dynamic Diagram
A dynamic diagram uses the same visual elements as the underlying static diagram. The additions are minimal.
Numbered Relationships
Each interaction in the flow gets a number. The numbers are sequential and show the order in which calls or events occur. Labels explain what is being sent or requested — "POST /api/orders", "fetch customer record", "publish OrderPlaced event".
You can use sub-numbers (1.1, 1.2) to show parallel steps or nested calls within a single top-level interaction.
The Same Boxes as the Static Diagram
Every element in a dynamic diagram comes from its parent static diagram. You do not invent new elements at this level. If you find yourself wanting to add a box that does not exist in the Container or Component diagram, that is a signal to update the static diagram first.
Optional Return Arrows
Return arrows are optional. Add them when the response is not obvious or when the data flowing back is important to the scenario being explained. Omit them when they clutter the diagram without adding information.
What Level Do You Draw Dynamic Diagrams At?
Dynamic diagrams can be drawn at any level of the C4 model:
- System-level (Context scope): shows how multiple systems exchange calls to handle a user scenario. Useful for cross-system integrations and API gateway patterns.
- Container-level: shows how services, databases, queues, and workers inside one system collaborate to handle a request. This is the most common level for dynamic diagrams.
- Component-level: shows how components within a container interact during a specific operation. Useful when internal complexity is high and the container-level view is too coarse.
The level you choose should match the level at which the question lives. "How does checkout work across our systems?" is a system-level question. "How does the Order Service persist and publish an event?" is a container or component question.
When to Draw a Dynamic Diagram
Dynamic diagrams pay off in three specific situations.
Explaining non-obvious flows. Some interactions are straightforward: the browser calls the API, the API queries the database, the result comes back. Nobody needs a diagram for that. Dynamic diagrams earn their place when the flow involves multiple hops, asynchronous steps, compensating transactions, or conditional branches that are not obvious from the static structure alone.
Documenting critical paths. Login, payment processing, data synchronisation, and backup procedures are flows that engineers return to repeatedly — when implementing, when debugging, and when something goes wrong at 2am. A dynamic diagram for each critical path gives the on-call team a reliable reference without requiring them to reconstruct the flow from code every time.
Onboarding engineers to a domain. A new engineer reading a Container diagram understands the structure. A new engineer reading a dynamic diagram for the "create order" flow understands how that structure comes to life. The two diagrams together give a much fuller picture than either one alone.
How to Build a Dynamic Diagram
Step 1: Choose a scenario
Pick one specific scenario — one user action, one event, one batch job. Dynamic diagrams are useful precisely because they are narrow. A diagram that tries to show all possible flows becomes unreadable quickly.
Good candidates for a first dynamic diagram:
- The happy-path flow for the most important user action
- The flow that is most frequently misunderstood by new engineers
- The flow that is most often involved in incidents
Step 2: Select the parent static diagram
Choose the Container or Component diagram that contains the elements involved in the scenario. All boxes in your dynamic diagram must come from this parent. If an element is missing from the parent, add it there first.
Step 3: Copy the relevant elements
Place only the elements involved in this scenario on the canvas. Leave out everything else from the parent diagram. A dynamic diagram for a payment flow should not include the support ticketing container unless it participates in that flow.
Step 4: Number the interactions
Add lines between elements in the order they occur. Number each line. Label each line with enough information that a reader can follow the flow without reading the code.
If a step is conditional ("only if the user is new") or asynchronous ("event is published and processing continues independently"), note that on the label.
Step 5: Add a title and scenario description
The title should name the scenario explicitly: "Checkout flow — payment authorisation", not "Dynamic diagram 3". A one-sentence description of the trigger and the boundary ("Triggered by the user clicking Pay. Ends when the order confirmation email is queued.") helps readers calibrate what is in scope.
Step 6: Review with the team
Walk through the numbered steps with an engineer who knows the flow well. Common findings at this stage: missing steps, incorrect ordering, labels that omit important information, and elements that should be in the Container diagram but aren't.
Common Mistakes
Drawing too broad a scenario. A dynamic diagram for "everything that happens when a user logs in, including MFA, session creation, audit logging, and account recovery" is usually too wide. Split it: one diagram for the happy path, one for MFA, one for recovery.
Inventing elements. Adding a box that does not exist in the parent static diagram to make the flow easier to explain means the static diagram is incomplete. Fix the static diagram first.
Skipping return arrows entirely. Return arrows are optional but sometimes essential. If the response carries important data (a session token, a transaction ID, an error code that triggers different behaviour downstream), include the return arrow and label it.
Using dynamic diagrams as sequence diagrams. If you find yourself adding lifelines, activation bars, and message parameters, you have left C4 notation and entered UML territory. For highly detailed message-level documentation, a proper sequence diagram is the better tool. Dynamic diagrams operate at the same abstraction level as the parent static diagram.
One diagram for all scenarios. Every important scenario deserves its own dynamic diagram. Combining multiple flows on one canvas with branching arrows produces something that is technically accurate and practically unreadable.
Dynamic Diagrams and the Rest of the C4 Model
Dynamic diagrams complement static C4 diagrams; they do not replace them. The static diagrams define the vocabulary. Dynamic diagrams use that vocabulary to tell stories.
A useful rule of thumb: draw the Container diagram (Level 2) first. Once that exists and is reviewed, identify the two or three flows that would benefit from a dynamic diagram and draw those. Do not draw dynamic diagrams before the static structure is stable — changes to the Container diagram require corresponding updates to every dynamic diagram that references it.
For teams adopting the C4 model incrementally, dynamic diagrams are often the last thing added. Start with the Landscape and Context diagrams to establish scope, move to Containers to establish structure, and then add dynamic diagrams for the flows that need it.
Frequently Asked Questions
Are C4 dynamic diagrams the same as UML sequence diagrams?
No. They share the goal of showing runtime behaviour, but dynamic diagrams stay within the C4 notation — they use the same boxes and relationships as the parent static diagram. UML sequence diagrams use lifelines, activation bars, and message syntax. Use a C4 dynamic diagram when you want to stay at the same level of abstraction as your other C4 diagrams. Use a sequence diagram when you need message-level precision.
Can a dynamic diagram span multiple systems?
Yes. If your scenario involves calls between systems you own, or between your systems and external ones, draw those systems on the canvas using their Context-level representations. The interaction lines get numbers just like any other dynamic diagram.
How many steps should a dynamic diagram have?
There is no hard limit, but diagrams with more than ten to twelve numbered steps become difficult to follow in a single reading. If your flow has many steps, consider splitting it at a natural boundary (for example, one diagram for the synchronous part and one for the asynchronous processing that follows).
Does every C4 diagram need a dynamic counterpart?
No. Static diagrams are the foundation. Dynamic diagrams are supplements for flows where the runtime behaviour is not obvious from the structure alone. Many Container diagrams will never need a dynamic counterpart, and that is fine.
Where do dynamic diagrams live in the documentation hierarchy?
They live alongside the static diagram they extend. If your Container diagram lives in a documentation section called "Payments Service", the dynamic diagrams for the checkout flow and the refund flow live in the same section. They reference the same parent and belong in the same context.