I’ve been learning about tooling and processes for understanding complex systems.
The main challenges of documenting these systems are determining who your audience is, knowing when to dive into additional detail, and utilizing consistency across various diagramns.
The C4 Model provides a structured approach to documenting software architecture, helping you communicate effectively with both technical and non-technical stakeholders. By embracing a framework for documenting systems, you can focus on uncovering relationships, letting C4 guide you to the appropriate levels of abstraction and documentation.
C4 Model Summary
The above site does a great job of simply describing the C4 model, but to summarize:
The C4 Model is a set of hierarchical diagrams to describe a system, where each successive diagram type is a more detailed view of the system.
- System Context
- Container
- Component
- Code
System Context diagram
The System Context diagram describes the highest level of abstraction and shows the top-level system, plus any users, and system dependencies.
Container diagram
Not Docker!
The Container diagram gives the overall shape of the architecture and technology choices of a system. As a rough rule of thumb, a C4 container would be any individually deployable unit that needs to be running for a system to work.
For example, if an individual system was a website, the container diagram might include nodes for the database, one or more backend servers, and a front-end client.
Component diagram
The Component diagram shows groupings of related functionality encapsulated behind a well-defined interface. As opposed to a container, a component is not an individually deployable unit.
On the other hand, while a component could be an individual class, it’s more likely a grouping of classes to represent a piece of functionality.
Code diagram
Lastly, a Code diagram shows the atomic building blocks of components and is often generated as UML. In most cases, you wouldn’t want, or need to explicitly create code diagrams, and instead, should rely on tooling to automatically create code diagrams dynamically while working.
Applying the C4 Model
As a concrete example, consider a simple ecommerce web application. Using the C4 Model, you might create:
- A System Context diagram showing the web app, users, and external services, like Stripe.
- A Container diagram including nodes for the front-end, back-end, and database.
- A Component diagram of the back-end container, highlighting things like authentication or payment components.
- Code diagrams wouldn’t be made initially – only dynamically created by IDEs as necessary.