C4 Code Diagrams: Visualizing Component Internals with UML Class Diagrams

1. What Is a Code Diagram?

The previous article covered the component diagram: drilling into a single container to show which components it comprises, their responsibilities, and their implementation technologies.

At this point, the C4 static structure has only one level left: the system context diagram for the whole system, the container diagram inside the system, the component diagram inside a container, and finally this level: code .

Code Diagram shows the implementation details inside a single component — opening the component further to see what code-level building blocks it is assembled from.

2. Key Attributes

Like the previous diagrams, to understand why and how to draw a code diagram, you must grasp its key attributes: intent, scope, content, why it is useful, and who needs to read it.

2.1 Intent

A code diagram depicts the internal code structure of a single component , helping you answer these questions:

What code-level building blocks is this component decomposed into?

Which of these building blocks are publicly exported and which are internal implementation details?

How large and complex is this component really?

The first two questions are the most practical: when a component's public contract and internal implementation are clearly separated, others know what they can depend on and what might change at any time.

2.2 Scope

The scope of a code diagram is locked to a single component .

As you will see next, if you are using an object-oriented language (OOP) such as Java, C#, or C++, then a UML class diagram is a good way to represent the code.

There is a historical lesson here. UML class diagrams were often used to describe an entire application , but that approach almost never works in practice. Imagine an application composed of tens of thousands of Java classes ; forcing it into a single UML class diagram yields a massive diagram crammed with tens of thousands of boxes and arrows . No matter how well the code structure is organized, such a diagram is useless.

Therefore, the key to using UML class diagrams is to limit their scope . The C4 code diagram does exactly that: its scope stops at the interior of a single component .

2.3 Content

A code diagram should show the various code-level building blocks supported by the programming language .

For Java and C#, that means classes and interfaces inside packages and namespaces . You could invent your own visual notation, but if you are using an OOP language, the simplest approach is to use UML class diagrams directly .

However, a warning: UML class diagrams very easily accumulate excessive detail, especially when you reverse-generate the diagram from existing code . You will be tempted to label every attribute and method of every class. Resist that urge — include only the information you need to tell the story clearly.

2.4 Why It Is Useful

Frankly: there are very few reasons worth drawing a code diagram .

Because the questions listed in 2.1 can basically be answered by glancing at the code .

That said, code diagrams are still useful in two cases: one is to provide a summary for exceptionally large and complex components , and the other is to illustrate how a specific pattern is implemented inside a component .

2.5 Audience

Unsurprisingly, the target audience for code diagrams is the engineers building or maintaining the software . This level of detail is usually too much for other readers .

3. Should You Draw a Code Diagram?

First, the conclusion: except for the most important and complex components, drawing code diagrams is not recommended .

The reason is direct. For already-written software , this level of detail already exists in the code , and code diagrams can usually be obtained on demand from tools such as an integrated development environment (IDE) .

This raises a question: since the code is right there, why does C4 define a dedicated code diagram level?

The short answer: it helps establish traceability from the entire software system all the way down to the code . What that reason truly implies is set aside for now.

4. Drawing a Code Diagram Step by Step

This time we drill into the Core Banking System Adapter component and draw its internal code.

As mentioned earlier, the implementation uses Java , an OOP language, so a UML class diagram fits perfectly.

4.1 Hand-Drawn

The Core Banking System Adapter component has a publicly exported interface CoreBankingSystemAdapter that defines the component's contract ; it also has a package-visible implementation class CoreBankingSystemAdapterImpl — it is package-protected, meaning it is only accessible within the same package and not exposed externally.

This implementation class uses the CoreBankingSystemConnection class to create and pool connections to the core banking system, enabling it to send XML requests and receive XML responses .

The key design point follows: each type of request to be sent is implemented by a dedicated class that knows how to format that request into an XML document ; correspondingly, each response is implemented by a class that knows how to deserialize the XML response into its own domain class .

The example shown in the diagram is the pair BankAccountsRequest and BankAccountsResponse — used for querying the collection of bank accounts belonging to a customer.

The component internally contains more elements such as authentication and error handling , but this simplified diagram is sufficient to explain how it works and to guide other engineers : future calls to the core banking system should follow the same pattern .

4.2 Reverse-Generated from Code

Besides hand-drawing UML class diagrams, there is another path: reverse-generating from code .

This path only works when the software already exists , and it by default will most likely show you too much detail .

This diagram illustrates well: at this level of detail, you can get what you need on demand from your IDE . The trade-off is that you may have to configure the generated diagram to hide those attributes and methods that do not help explain a particular feature .

1. The C4 Model for Visualising Software Architecture Chapter 6 ↩︎