An architecture that exists only in its author's head is a lost architecture. Documenting it is what allows the team to understand it, new members to onboard quickly, the business to trust what is being built, and decisions to survive personnel turnover. But documenting well is hard: diagrams tend to become outdated, mix levels of detail, or turn out to be incomprehensible to anyone who did not draw them. In this lesson you will learn two fundamental tools: the classic 4+1 view model by Philippe Kruchten and, above all, the modern C4 model by Simon Brown, a simple and pragmatic way to diagram architectures with four zoom levels: Context, Container, Component, and Code.

1. Why document and for whom
2. The 4+1 view model
3. The C4 model: the zoom idea
4. Level 1: Context diagram
5. Level 2: Container diagram
6. Level 3: Component diagram
7. Level 4: Code
8. Best practices and tools

Documenting is not about producing hundreds of pages no one will read. It is about communicating effectively to different audiences. The main rule: document just enough, for a specific audience and with a clear purpose.

A classic mistake is to use a single giant diagram for all audiences: it ends up being too detailed for the business and too superficial for the developer. The solution is to offer different views at different levels.

Proposed by Philippe Kruchten in 1995, the 4+1 model starts from the idea that no single view captures the entire architecture. It proposes four views plus one cross-cutting view.

This Mermaid diagram places the scenarios at the center, connected (with ---, undirected lines) to the four views. The idea is that key use cases "bind" and validate the other views: every important scenario must be traceable through the logical, process, development, and physical views. The 4+1 model remains conceptually valuable, but in day-to-day practice many teams today prefer C4 for its simplicity and its direct mapping to how software is actually built.

The C4 model, created by Simon Brown, is based on an analogy with maps: just as you use different zoom levels (world, country, city, street), an architecture is best understood with different levels of detail. C4 defines four levels, each a "zoom" into the previous one:

Basic C4 concepts:

• Person: a human user of the system (customer, administrator...).
• Software system: what you build (or an external system you integrate with).
• Container: not necessarily a Docker container; it is something that runs and is deployed independently: a web application, an API, a database, a single-page app, a broker.
• Component: a logical grouping of functionality within a container.

A C4 golden rule: most teams routinely need only levels 1 and 2, and level 3 occasionally. Level 4 is almost never drawn by hand, because the IDE generates it.

This is the highest level. It shows your system as a single box, surrounded by its users and the external systems it relates to. Its purpose is for anyone, including the business, to understand the big picture.

This Context diagram shows a single box for "Online Banking System," surrounded by a person (the Customer) and two external systems (Email and Banking Core). The labeled arrows describe what each relationship does, not how. Note that no technology or internal detail appears: at this level all that matters is the system's scope and its interactions with the outside world. It is the ideal diagram to start any conversation, including with non-technical people.

We zoom inside our system. We show the deployable units that make it up and how they communicate, now indicating the main technologies.

Here, inside the online banking system, we see three of our own containers: a single-page web application in React, an API in Java with Spring Boot, and a PostgreSQL database; plus the external system (Banking Core). Each arrow indicates the communication protocol (HTTPS, JSON, SQL). This level is the most useful in day-to-day technical work: it shows at a glance the deployment architecture, the chosen technologies, and the communication flows. Remember: "container" here means deployable unit, not necessarily a Docker container.

Now we zoom inside a single container—for example, the Banking API—to see how it is organized internally into components.

This diagram uses a subgraph to represent the boundaries of the Banking API and shows three internal components: the REST controller that receives requests, the service that contains the business logic, and the repository that accesses the data. It is the classic separation into layers (presentation, business, data) within a container. This level is valuable for helping developers understand the internal structure, but it should be drawn only for non-trivial containers, not for all of them.

The last level details how a specific component is implemented, usually with a UML class diagram. In practice, it is almost never drawn by hand: the IDE or documentation tools generate it automatically, because it changes constantly and maintaining it manually is wasted work.

This code shows how the "Transfers Service" component materializes into concrete classes. The C4 recommendation is not to draw this level manually: if you need to see it, let your IDE generate the class diagram from the actual code. Keeping code diagrams by hand is the number one cause of outdated documentation.

Summary of the notations and practices recommended by C4:

• Every diagram self-explanatory: with a title, a legend, and clearly labeled elements.
• Label the relationships: describe what each arrow does and, where applicable, with what technology/protocol.
• One level per diagram: do not mix context with code.
• Do not overuse levels 3 and 4: draw only what adds value.
• Documentation as code (diagrams as code): define the diagrams in text so they can be versioned alongside the code and avoid becoming outdated.

Common tools:

Example of the same context diagram in PlantUML with the C4 extension:

This PlantUML snippet uses the official C4_Context library. The Person, System, and System_Ext (external system) macros create the elements with their name and description, and Rel defines the labeled relationships. The advantage over Mermaid is that PlantUML with C4 knows the model's semantics (it distinguishes people from systems, internal from external) and applies a consistent style automatically. Being text, it is versioned alongside the code and regenerated effortlessly.

• The "spaghetti-plate diagram." A single diagram with everything mixed together communicates nothing. Separate by levels and audiences.
• Diagrams without a legend or labels. If the boxes and arrows are not explained, each reader interprets whatever they want. Label everything.
• Documentation that ages. Hand-drawn diagrams become outdated quickly. Use diagrams as code and generate the code level automatically.
• Excess detail. Do not draw levels 3 and 4 for everything. Most teams live happily with levels 1 and 2.
• Tip: always start with the Context. In any architecture conversation, start with the context diagram; align everyone before descending into detail.

Exercise 1. Match each element with its C4 level: (a) "a Redis database"; (b) "the customer and the external payment system"; (c) "the OrdersService class"; (d) "the controller, the service, and the repository within the API."

Exercise 2. Draw (in Mermaid or PlantUML) a Context diagram for a library management system, with at least one person and one external system.

Exercise 3. Explain why C4 recommends not drawing the Code level manually and what alternative it proposes.

Solution 1. (a) Container (level 2): a database is a deployable unit. (b) Context (level 1): people and external systems. (c) Code (level 4): a specific class. (d) Component (level 3): logical groupings within a container.

Solution 2. Example in Mermaid:

This Context diagram shows two people (Member and Librarian), our own system, and an external Email system, with labeled relationships describing what each interaction does, without going into technologies or the internal structure.

Solution 3. Because the code changes continuously, and maintaining a class diagram by hand quickly turns it into outdated and unreliable documentation, which creates more confusion than help. The alternative C4 proposes is to generate this level automatically from the code itself (with the IDE or documentation tools) when it is genuinely needed, instead of drawing it manually.

You have learned why and for whom an architecture is documented, the classic 4+1 view model and, in depth, the C4 model with its four zoom levels (Context, Container, Component, and Code), plus the practices and tools for keeping documentation alive through diagrams as code. With this you close Module 1, Fundamentals of Application Architecture: you now know what architecture is and its domains, who the architect is, how quality attributes are specified, how decisions and their trade-offs are made and documented, and how to communicate all of it clearly. On these foundations, the following modules will delve into the concrete architectural styles and patterns with which to bring these ideas to life.