I think a great rule for drawing boxes-and-lines architecture diagrams is: never have overlaps or cycles.
If you can't avoid one or both, it's a sign that you're providing too much detail. Zoom out to a different conceptual level, or split the diagram up.
The point of boxes-and-lines diagrams is to quickly incept your system model into the mind of someone without much context. (Maybe even yourself, after an e.g. vacation!) Choose simplicity over completeness. ASCII is often the best choice because it forces you to stay simple.
Diagrams are the on-ramp to establish a shared context, but they're most effective when combined with (simple!) prose describing components and behavior in more detail. Again, stay at a high level: readers will dig in to other docs or code if they want more detail.
An ideal README has a 1–2 sentence description of the project, and then a high level system diagram, with a couple paragraphs of explanation. The goal is to provide context for understanding the project in relation to other projects, and for understanding further docs/code.
c4model.com just before I left TomTom started putting it in to replace all UML etc. There are also PlantUML templates to be found in the wild... as close to a standardized ansi graphs that I can currently think of...
from what I understood the idea is to not insist on the deepest level, only if it does provide value to explain a complex sequence of events or some important impl detail, the highest 3 are more important
I've used C4 a few times, and my favorites constraints which improve diagrams are:
- it forces you to label your arrows
- it forces you to keep all boxes at the same abstraction level
It makes a huge difference in making the diagrams easy to grasp
Also a shame Container means something else... spitballing, I like Systems (high level, logical parts of an architecture), Processes (discrete, running artifacts implementing part or all of a system) and Components (well-defined code entity implementing part of a process)
“container” wasn’t a term widely in use when I came up with the terminology ~2011. I did consider “process”, but that breaks down quite quickly when you look at how (e.g.) multiple Java EE apps packaged as .war/.ear files can be run in a single Java process. Naming is hard. 😀