DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Refcards Trend Reports Events Over 2 million developers have joined DZone. Join Today! Thanks for visiting DZone today,
Edit Profile Manage Email Subscriptions Moderation Admin Console How to Post to DZone Article Submission Guidelines
View Profile
Sign Out
Refcards
Trend Reports
Events
Zones
Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
  1. DZone
  2. Software Design and Architecture
  3. Microservices
  4. Documenting the Architecture of Your Projects With the C4 Model

Documenting the Architecture of Your Projects With the C4 Model

Learn what the C4 model is and why to use this model to document architecture. Furthermore, see what we've been doing in Zup's Open Source products.

Otavio Santana user avatar by
Otavio Santana
CORE ·
Dec. 22, 21 · Analysis
Like (9)
Save
Tweet
Share
16.08K Views

Join the DZone community and get the full member experience.

Join For Free

One of the definitions used to approach software architecture is that it is responsible for defining the parts of a project and the technological strategy. And, like any strategy, there must be an ongoing process of review and update. That's why, here on the Zup Open Source team, we're using the C4 model.

Having a view of your project's architecture is crucial in several aspects, as it helps you answer questions such as: how can my system integrate internally or with other systems? Or, how can I guarantee security between my applications? And so on.

One of the classic architecture books, Just Enough Software Architecture: A Risk-Driven Approach, mentions that to make software successfully, you have to deal with three fronts:

  1. Partition: The art of dividing the problem into small pieces to understand a whole.
  2. Knowledge: The ability to explain what is behind the architecture, how it works, but mainly why it is used, and what were the necessary decisions to reach this final result.
  3. Abstraction: A software architecture definition is difficult to define precisely, so using stereotypes helps understand and solve complex problems.

Another reference book in the area, called Fundamentals of Software Architecture: An Engineering Approach, states that the constant analysis of architecture is one of the requirements expected by those who work with architecture within technology.

Given the alternatives available on the market for documenting software architecture, which one might be a good choice?

What is the C4 Model?

Documenting the architecture of a project is often a painstaking process that requires time, knowledge of tools, and techniques for diagramming and documentation.

In practice, the biggest challenge within software architecture documentation is to avoid two scenarios:

  1. Architectural documentation is very complex and, as a result, tends to become confused and obsolete, losing its purpose. In other words, documentation takes time and becomes unusable in a short time.
  2. "Poor" documentation with little information or incorrect information that we don't spend time creating, but it is useless.

In either case, the result is that they are more of a hindrance than a help.

The C4 model is a documentation format created by engineer Simon Brown between 2006 and 2011 and based on the 4+1 and UML document models.

It came about to help solve the problem of documenting faulty architectures that are difficult to understand and maintain. The C4 model clarifies the documented architecture and spans several levels relevant to the various “personas” involved.

The Levels of The C4 Model

The C4 model has four types of diagrams, each of which has a different level of detail and target audience. The idea is to dig deeper into the details and information from the previous story.

A better allusion would be with Google Maps, which you can zoom in to reduce or enlarge the architectural design. If on a map, for example, we have Continent, Country, State, and City, on the C4-model we have:

  • Context.
  • Container.
  • Component.
  • Code.

Below, we will better understand each of the levels:

Level 1: Context

It's the first step in our design. The idea is to show interactions in a macro way, without much detail, focusing on communications and dependencies between systems and users composing and interacting with the software.

It is a diagram that can (and should) be consumed by all the "personas" of the project, both technical and business, and that interact directly or indirectly with the system.

C4 Model Context Diagram Example

Level 2: Container

The second level shows the system in more detail, describing its containers (not to be confused with Docker) and how they communicate/interact. At this level, emphasis is on the architecture and technologies used.

The idea is to show how the system is (or will be) built in a macro way. A container can be a web application, a database, a file system, among others. It is a diagram to be consumed by the technical team, which interacts directly or indirectly with the system (development, support professionals, etc.).


C4 Model Container Architecture Diagram Example

Level 3: Component

Upon reaching the third level, we take a further step in the details compared to Container, this time with the description of the parts that make up these containers. At this level, information about interactions, responsibilities, and technologies used appears in more detail than at previous levels.

A system will likely have more than one component diagram. It is a diagram to be consumed by the technical development team, which is recommended only in cases that have generated value. There is a commitment to maintaining it.

C4 Model Component Diagram Example

Level 4: Code

At the last level, the C4-model shows - at the code level - how each component is implemented and for that, it uses the UML class diagram.

Generally speaking, this level of detail is not recommended and is an optional view. Furthermore, several tools currently generate this type of diagram automatically.

Why Do We Adopt the C4 Model for The Architecture of Our Projects?

Within Zup's Open Source team, the technology and architecture of each project are viewed strategically, as we understand that having a clear vision of what we are building - both at a technical and business level - contributes to the evolution of the product and the creation of solid roadmap.

An excellent technological product is based on solid architecture and its respective documentation. Therefore, with the C4 model, we could have this vision in an agile way and add value to the project.

Furthermore, this model allows us to share the project's architectural knowledge with the community, simplified but with purpose and value.

How We Use the C4 Model

On the team, we advocate that the architectural documentation needs to stay close to the code and is the responsibility of all team members. Like the code itself, our C4 model is inside a Git repository.

It guarantees all the benefits of versioning. By the way, we strongly believe in the doc as a code, where we also have all our documentation.

To facilitate the visualization and maintenance of the C4 model, we adopted the model of a single repository per project, available via S3 and deployed using GitHub Actions.

What Tool Do We Use?

We adopt the architectural design as code with C4-Builder. The primary point is that it has different ways to configure and export. However, among the existing settings, we chose to use it via markdown, since it is the tool that:

  • We already use it for our documentation;
  • Our Technical Writers team recommends;
  • It is doc as a code, being in line with our purposes and guidelines;
  • It has an action for GitHub Actions, a tool used in our pipeline, which facilitates the integration and use of the instrument.

How Do We Align the C4 Model With the Documentation?

Following our technical documentation pattern, our C4-model models are available online via a website referenced in a menu in the official documentation.

It is the responsibility of the Engineering team, together with the Technical Writing team, to keep the C4-model up to date with each update in which it is necessary to update the architecture documentation as well.

You can check the C4 model of each project:

  • Charles CD
  • Horusec
  • Ritchie CLI
  • Beagle

C4 Model: The Key to The Evolution of a Project

Good documentation is at the heart of any Open Source project and is generally the gateway to open source projects. With architecture, this is no exception.

Software architecture Open source Documentation agile Docker (software)

Opinions expressed by DZone contributors are their own.

Popular on DZone

  • How to Develop a Portrait Retouching Function
  • Why Every Fintech Company Needs DevOps
  • Spring Cloud: How To Deal With Microservice Configuration (Part 1)
  • PostgreSQL: Bulk Loading Data With Node.js and Sequelize

Comments

Partner Resources

X

ABOUT US

  • About DZone
  • Send feedback
  • Careers
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 600 Park Offices Drive
  • Suite 300
  • Durham, NC 27709
  • support@dzone.com
  • +1 (919) 678-0300

Let's be friends: