Mike's Notes
Pipi is highly complex, with a novel architecture that resembles a moving biological cell, so diagramming to aid understanding will be very challenging.
The C4 model by Simon Brown may be a valuable tool for Pipi to automatically document itself because it follows simple rules and can zoom in and out. Many other tools will also be needed. Some may have to be invented.
Chris Richardson's diagrams look useful as well.
Resources
- https://www.reddit.com/r/softwarearchitecture/comments/1oos3oe/ama_with_simon_brown_creator_of_the_c4_model/
- https://simonbrown.je/
- https://c4model.com/
- https://structurizr.com/
- https://docs.structurizr.com/onpremises
- https://www.youtube.com/watch?v=FwG3KGa9-WE
- https://youtu.be/x2-rSnhpw0g?si=ug3xu_zHX9TBHpIh
References
- Reference
Repository
- Home > Ajabbi Research > Library >
- Home > Handbook >
Last Updated
23/12/2025
C4 for documenting architecture
I'm the author of Software Architecture for Developers; a developer-friendly guide to software architecture, technical leadership and the balance with agility. I'm also the creator of the C4 software architecture model and the founder of Structurizr, a collection of tooling to help software teams visualise, document and explore their software architecture.
Ask somebody in the building industry to visually communicate the architecture of a building and you’ll be presented with site plans, floor plans, elevation views, cross-section views and detail drawings. In contrast, ask a software developer to communicate the software architecture of a software system using diagrams and you’ll likely get a confused mess of boxes and lines … inconsistent notation (colour coding, shapes, line styles, etc), ambiguous naming, unlabelled relationships, generic terminology, missing technology choices, mixed abstractions, etc.
As an industry, we do have the Unified Modeling Language (UML), ArchiMate and SysML, but asking whether these provide an effective way to communicate software architecture is often irrelevant because many teams have already thrown them out in favour of much simpler “boxes and lines” diagrams. Abandoning these modelling languages is one thing but, perhaps in the race for agility, many software development teams have lost the ability to communicate visually.
Maps of your code
The C4 model was created as a way to help software development teams describe and communicate software architecture, both during up-front design sessions and when retrospectively documenting an existing codebase. It’s a way to create “maps of your code”, at various levels of detail, in the same way you would use something like Google Maps to zoom in and out of an area you are interested in.
System Context
Container Diagram
A container diagram zooms into the software system in scope, showing the applications and data stores inside it.
Component Diagram
A component diagram zooms into an individual container, showing the components inside it.
Code Diagram
A code diagram (e.g. UML class) can be used to zoom into an individual component, showing how that component is implemented at the code level.
Uses and benefits
Good software architecture diagrams assist with communication inside and outside of software development/product teams, efficient onboarding of new staff, architecture reviews/evaluations, risk identification (e.g. risk-storming), threat modelling, etc. The goal of the C4 model is to raise the level of maturity associated with software architecture diagrams.
No comments:
Post a Comment