4C - an agile approach to architecture discovery and documentation

4C - an agile approach to architecture discovery and documentation

We had the opportunity to talk to Kamil about a very interesting issue, which is the documentation of system architecture. How to do it so as to include all the necessary information and not overload it with details? Kamil presented an approach to documenting the architecture called "C4". The name comes from the fact that it takes place on 4 levels: Context, Containers, Components, Classes. The "C4" approach was also presented at one of the first CSD+ meetings when we were looking for easier ways to present system architecture. The need for a new solution was the result of experiences from concept meetings with customers. Unfortunately, not everyone understands UML notation, which caused problems in identifying key information. "C4" is a simplified way of showing architecture, where we divide everything into 4 diagrams:

  1. Context - the general context in which the system will work: main actors/roles, other systems, main processes
  2. Containers - high-level decisions, "houses" for components, high-level communication, information for developers about where to do work
  3. Components - logically coherent parts of functionality (e.g. services), system operation on the level of flow between components
  4. Classes - structures for classes, application architecture (ordering of source code)

It is also important to note that in the 'C4' approach, aspects are approached differently at each level:

  1. Purpose - what is the purpose of the diagram, what should it represent
  2. Structure - which blocks make up the diagram
  3. Motivation - what do we want to communicate to the audience of the document and what discoveries can be made during its creation
  4. Recipients - who the recipients are and what they might need at a given level of detail

Within C4, we use simple, often self-defining diagrams and a single, defined notation. By implementing the C4 methodology, we use the same set of abstractions and the same notation at every level of detail, in communication with every possible audience. The C4 approach provides us with consistent "information scaling" without semantic gaps. This allows us to verify the architecture - in the sense of its current alignment with requirements and context. Verification is facilitated by the ability to seamlessly scale attention from the general to the specific, allowing us to gradually familiarize ourselves with the context. An example of how C4 can be used can be found in our GitLab Wiki at: https://git.inf.nekken.loc/nekken-public/c4-demo