C4 model:

• (System) Context: system, user and other systems - OVERVIEW (highest level)
• Containers: architecture and technology of a system - it is a zoom inside a system - services, databases - calls between them etc…)
• Components: logical components inside a container. e.g. a service or frontend (controllers, facades, etc…)
• Code (e.g. classes) inside a component. (it should be generated by an IDE, it is the lowest level and the most hard to keep updated)

“Diagrams as maps”: so developers can navigate through a system

Each diagram must have:

• Titles
• Visual consistency

Start with simple boxes with: (e.g. https://youtu.be/x2-rSnhpw0g?t=1410)

• Element name
• Type
• Technology (if it applies)
• Description
• Responsibilities

Uni-directional lines (arrow must match the flow and have a description). Avoid bidirectional arrows, unless the arrows have different labels with different intentions (e.g. https://youtu.be/x2-rSnhpw0g?t=1611)

Avoid much lines, because they make diagrams confusing and can hide the true story (e.g. do not do https://youtu.be/x2-rSnhpw0g?t=1649, and instead do https://youtu.be/x2-rSnhpw0g?t=1665).

AVOID complexity and clutter in diagrams. KISS. Increase readability

Use shapes to ease the understanding: https://youtu.be/x2-rSnhpw0g?t=1851 (the image on the right is much better.

Text must complement a diagram rather than explain it. You can write more detailed text, based on an existing C4 model.

Tools: (do NOT use visio, draw.io, etc… they are general-purposing diagramming tools)

• C4-PlantUML (you can describe diagrams as text and it makes the drawing).
• Structurizr
• https://github.com/tobiashochguertel/c4-draw.io

Ensure the team has a language to describe software architecture.