C4 Model Diagrams

Choose a zoom level for the question

The C4 model organizes software architecture diagrams into four levels of zoom: system context, containers, components, and code. The levels answer different questions rather than asking an architect to draw every detail at once. A context view explains which people and external systems interact with the system of interest. A container view opens that boundary to show deployable or runnable units and their responsibilities. A component view zooms into one container's major building blocks. A code view can show implementation structure when a specific design question requires it.

The word container in C4 means an independently runnable or deployable unit, not necessarily a Docker container. A web application, API, background worker, or database can each be represented as a container. Label technologies only when that information helps the audience understand constraints or interfaces. The diagram should make system boundaries and relationships legible without turning into an inventory of every library.

Context view

A system context diagram places the system in its environment. Show the people or roles that use it, the external systems it depends on, and the relationships among them. The intended audience may include product owners, security reviewers, and engineers. Keep the notation simple enough that a reader can answer: what is inside the boundary, who uses it, and what systems exchange information with it?

Context diagrams are useful for scope conversations and integration discovery. They can expose an undocumented dependency, a manual operational role, or an external identity provider that changes a security assumption. They do not explain deployment topology or internal component structure. Adding internal classes to this view defeats its purpose and makes the system boundary harder to see.

Container and component views

The container view shows the major applications, services, data stores, and execution processes that make up the system. Name each unit by responsibility and show important communication paths, protocols, and data direction. It can support deployment planning, operational readiness, and ownership discussions. Do not show every runtime instance unless scaling topology is the question; instance counts change more often than architectural responsibilities.

A component view examines the internals of one container. It can show application services, adapters, modules, and their dependencies. Keep it scoped to the container and purpose of the discussion. Component boundaries should reflect meaningful responsibilities and dependency direction, not a one-box-per-class convention. If the diagram starts to resemble a full code browser, it is probably at the wrong altitude.

The code level can use class or package diagrams to answer a detailed implementation question, but it is rarely a durable overview. Source code is already authoritative for many code-level details and changes quickly. A code diagram is most useful when it explains a design pattern, extension point, or dependency constraint that is difficult to infer from source alone.

Relationships and notation

Every relationship should have a direction and a short label explaining the interaction, such as submits orders, reads records, or publishes events. Avoid unlabeled arrows whose meaning must be inferred from layout. Include protocol or data technology when it influences integration behavior, such as HTTPS, a queue, or a database driver. Use a consistent legend for colors and shapes; visual styling should clarify boundaries rather than encode undocumented meaning.

C4 is a model for communication, not a mandatory tool or file format. A diagram can be created with a drawing tool, text-based notation, or code, as long as the result is readable and maintained. Keep a source version under review and make the rendered artifact accessible where decisions occur. The most useful diagram is the smallest one that supports the current decision and can be kept accurate by its owners.

Work from context inward

Start with a real system and one audience question. For an order platform, a context diagram might show a customer, support operator, order platform, payment provider, and shipping service. Label relationships in plain language. Agree on the system boundary before discussing internal services; otherwise teams often disagree about whether a shared identity service or analytics pipeline belongs to the system under review.

Next draw the container view. Show the browser application, public API, order worker, relational database, and message broker if those are meaningful runtime units. Label protocols and the direction of important data flows. If the API writes an order and publishes an event, make the transaction or asynchronous boundary visible because it affects consistency and failure handling. Do not draw every cloud resource unless the question concerns deployment or operations.

Choose one container to open for a component view. For the API, the diagram might show route handlers, application services, payment adapter, repository, and event publisher. Indicate dependency direction and the external boundary. Keep the view limited to the path under discussion, such as placing an order. This makes the drawing useful for code review and helps identify where a cross-cutting concern belongs.

Use consistent descriptions

Each box should have a name and a concise responsibility. Add a technology label when it matters, but do not make a technology list the responsibility. An arrow should say what moves or what is requested. If an interaction is asynchronous, label it as event publication or queue consumption instead of drawing it like a synchronous call. If data is replicated or eventually consistent, note that only when it affects the decision.

Create a legend for any color or shape that carries meaning. Avoid relying on color alone to communicate ownership or trust boundaries; labels and line styles should preserve meaning in grayscale and for readers with color-vision differences. Keep text readable at the size where the artifact will actually be reviewed. Splitting a large model into linked diagrams is better than shrinking every label until the picture fits on one page.

Review and keep the model current

Ask a reader who did not create the diagram to explain its boundary and one critical flow. If they infer a different responsibility or direction, revise the labels. Check that deployment units, external dependencies, data stores, and actor roles align with current code and operations. A diagram that contradicts reality is worse than no diagram because teams use it to plan changes, estimate risk, and respond to incidents.

Keep diagram source close to the architecture documentation or repository that owns the system. Use a review process for changes that affect system boundaries, data flow, or deployment responsibility. Generated diagrams can reduce drift if the source data is trustworthy, but automatic generation does not decide which details matter to an audience. Preserve a concise curated view for decisions and use generated detail as supporting material.

Exercise the levels by taking one current debate and asking what zoom level answers it. A leadership discussion about third-party dependencies needs context. A deployment review needs containers. A module ownership change needs components. A code-level extension point may justify a code view. If the diagram cannot change the decision or shared understanding, do not add detail solely to make it look complete.

Avoid the all-in-one diagram

One giant diagram often mixes people, cloud resources, classes, network ports, and third-party products. The result is dense but not necessarily thorough: readers cannot tell which details are stable, what belongs inside the system boundary, or what question the diagram answers. Separate views by zoom level and audience. Provide navigation between related views when a reader needs to trace from context to a container or component.

The opposite problem is a diagram so abstract that it omits consequential boundaries. A context view should still name important external systems and relationships. A container view should show the data stores and protocols that influence reliability or security. Selective detail is the goal: include facts that change the conversation, omit detail that creates maintenance cost without improving understanding.

Treat relationships as claims

An arrow is a claim about dependency or communication. Direction, protocol, and interaction style matter. A synchronous request can fail differently from an asynchronous event, and a read dependency differs from a write authority. Use labels to expose those distinctions. Mark trust boundaries when authentication or data handling changes at a boundary, and show ownership when it affects change coordination.

Technology choices can date quickly. Put vendor or framework labels on a view when they help answer a question, but avoid treating the diagram as a complete bill of materials. Keep volatile deployment scale in a separate operational view if it changes frequently. A context diagram usually should not become a cloud-provider diagram merely because the system is hosted in one cloud.

Maintenance and accessibility

Assign an owner and a review trigger. A new external dependency, service boundary, data store, or integration protocol should prompt an update. Version-controlled source makes changes reviewable and helps teams compare architecture over time. If diagrams are generated, verify their labels and scope rather than assuming a correct rendering implies an accurate model.

Make diagrams usable at normal viewing size. Use readable labels, consistent shapes, and sufficient contrast. Provide text descriptions or an adjacent relationship list for important diagrams so the information is not available only through spatial layout. Avoid encoding critical trust or ownership distinctions with color alone. These choices make the artifact more usable in documents, small screens, and assistive workflows.

In an interview, explain the four levels and choose one based on the audience's question. Clarify that a C4 container is a runnable unit, not specifically a Docker image. Describe how labels communicate relationships and why one all-in-one diagram fails. Finish with the maintenance rule: diagrams are valuable when ownership and review keep their claims aligned with the system. Keep a text description or relationship list alongside complex visuals so key information remains available when a diagram is viewed at reduced size or with assistive technology. Review the artifact after changes to ownership, trust boundaries, data flow, and deployment responsibilities, not only during periodic documentation cleanup. Ask an uninvolved reader to trace one important interaction and correct any ambiguity before publishing the view. This review prevents stale assumptions from becoming design constraints.