Software System Diagrams
Why we need to draw software system diagram? It is to communicate to others. However, if your system is complex, there is a challenge because brain short-term memory usually can only store 7 things at a time (or between 5 to 9). When a single diagram contains too many things, it is hard to communicate effectively. Generally for any type of complex concept, the pyramid principle is pretty useful. The idea is to group and organize into different levels, so in each group and level, item numbers can be controlled under what short-term memory can store. C4 model is taking the same approach for layering software system into different levels (each level provides a zoom-in view of level above it), providing a structured and consistent way to model software architecture. By dividing the system into smaller, independently deployable and scalable containers and components, it provides a more detailed and modular view of the system that is easier to comprehend and explain for different types of audience.
Let’s use e-commerce system as example.
Context: A Context diagram shows the relationship between the system that you’re building and other actors, including humans and non-human systems, such as external systems. This diagram is above the level of the microservices. In the e-commerce system, the context diagram would show the system as a single box representing the whole e-commerce application, with external dependencies such as payment gateways, shipping providers, and customer data stores as separate boxes around it.
Container: A Container diagram shows the containers that your final system is deployed into and their relationship to each other. If you’re following the “one container per microservice” rule, you can use this diagram to see all your microservices and the services that they depend on at a glance. In the e-commerce system, a container diagram might show multiple microservices containers, e.g. order management service, inventory management service, and product catalog service. Each microservice is represented as a separate box with its own API, e.g. order submission service, order tracking service, etc.
Component: A Component diagram, which isn’t always needed but is useful, provides a view within a container and a view of the interacting components. This diagram is useful when you’re using libraries and frameworks like Spring or Node because the diagram surfaces the high-level dependencies of your microservices implementation. In the e-commerce system, the component diagram can break down the components in order management service further, e.g. order submission component can have order validator, order processor, database; order tracking component can have order status tracker, order location tracker.
Code: This is lowest level of C4 model, usually contains detailed diagrams like UML class diagram. In the e-commerce system, the code diagram for order validator is dependent on order class, which is further dependent on orderitem class (dependent on product class), customer class, address class, paymentmethod class.
C4 model also supports other supplementary diagrams like System Landscape Diagram, Dynamic Diagram (sequence or numbered interactions between actors and applications), Deployment Diagram.
Software architecture tools
Some good articles about Software architecture tools
Software architecture tools can be categorized into three groups
modelling tools: IcePanel, Enterprise architect, Archi, Visual Paradigm, Gaphor, StarUML, Archipeg, GenMyModel, Aplas
diagrams as code: Structurizr, PlantUML, Ilograph, Mermaid.js, Diagrams
diagramming tools: Diagrams.net, Lucidchart, Miro, Excalidraw, tldraw, Gliffy, OmniGraffle, CloudSkew
Modeling and diagrams as code tools are better suited for long-term documentation, while diagramming tools are better for quick one-off sketches.
C4 model inventor Simon Brown recommends specific software architecture tool than general one, Structurizr, Mermaid, PlantUML.
C4 with Mermaid
C4 model with Structurizr
ChatGPT
I like diagrams as code. It is easy to maintain and update. With ChatGPT, it is even easier to get started with software diagram. Here is a post about using ChatGPT to generate Mermaid diagram. According to my test, the support for Structurizr is not that good.
Mermaid
Complex State Diagrams
Entity Relationship Diagrams (ER Diagrams)
Gantt Charts
User Journey
You can tell ChatGPT to add or remove components or relationships
Other Mermaid features: color the boxes, add icon to box (you can copy the official example to teach ChatGPT to put icons), styling the Boxes Shape (using Font Awesome icon)
Appendix
C4 model
https://www.ibm.com/garage/method/practices/code/c4-model-for-software-architecture/
