10 ms·
Architecture diagrams enable better conversations
- taeric 3y agoI'd love to see some examples. I know that the article mentions this as a downside of C4 diagrams, so consider this a plea to action from folks. I'd love to see examples of how these help. On the onboarding story, I'm specifically curious how/why diagrams work more than a bulleted list and other conventions could already do? What are the entry points? Is there a convention on how entry points are named? If not, why not? I love the idea of having a diagram that works as a reflection of the codebase. Hard not to think of ways that can help. I'm always worried that too much effort goes into the reflection, though. Especially when it is front loaded in the effort.
- kzhen 3y agoHi taeric, author of the article here > On the onboarding story, I'm specifically curious how/why diagrams work more than a bulleted list the point I was trying to make in the article was that having a visual representation helps new developers to build up a mental model of the different components of a software system. In my particular case the system in question is made up of: 2xAPI, 2xEvent Processors, Event Producer as well as dependencies on external systems. The architecture diagrams are helpful here as the new developers are able to see the interactions between components. > I love the idea of having a diagram that works as a reflection of the codebase. In C4 there are 4 levels, the first is the system view this doesn't bear much resemblance to the codebase, the second is the container level, this is where you show the different components that make up a system. It's important to note here that a component is a deployable "thing", e.g. an API, database, powershell/bash script etc. This is where you start to see a bit more of a link between the architecture diagrams and the codebase. My experience of level 3 and level 4 where you start to model the actual codebase didn't bear much fruit and there are tools which can do a good enough job here from scanning the code (particularly in the dotnet world, NDepend does a brilliant job, although £££s)
- taeric 3y agoI didn't say it directly, but thanks for the article! My question is probably more asking exactly how/why the visual representation helps. I am very open to the idea that they do. But I'm also open to the idea that it is the active interaction with others that is the important part. That it is done with text or with drawings feels secondary. Almost distantly. Your point about the really high level views of 1 and 2 in the levels feels notable. I also really resonate with the idea of identifying the deployable "things" that can be independently reasoned about. If you have a team that is pushing libraries between the two things, you then have to expand this discussion to the build and deploy systems as being integral to your team, not merely secondary considerations.
- ewi_ 3y agoI believe that the way we represent information is key to understanding. Data points in a list are usually way less insightful than a good graph (emphasis on good). What I have found is that it's the case in describing system architecture as well. As you say, you can describe a system in a few paragraphs, explaining the relationship between the main components. However, as paragraphs it can harder to grok, and also harder to write with no ambiguity. Now, part of what I say above can be seen as personal preference (text vs image), but in practice I have found that when using tools like plantuml or mermaid to make C4 diagrams, the result is easier to use, remember, and update than plaintext.
- taeric 3y agoI think I mostly just disagree, here. I want a graphical representation to be more impactful. But typically any system that scales such that a short list can't explain entry points and dependencies has scaled beyond what graphical tools can do, as well. Now, story boarding a communication sequence between systems can make great use of layout. So, I definitely see potential.
- gav 3y agoI believe that one of the big things that diagrams help with is maintaining state while having a conversation. You don't have to keep track of so many things in your head and it works in a similar way to the "tell ’em what you’re gonna tell ’em, tell ’em, and then tell ’em what you’ve told ’em" style of presenting--your audience gets to see up front what journey you are taking them on. There's a great book by Abby Covert about diagrams in general: "Stuck? Diagrams help."[1] From a learning perspective, having multimodal[2] options, such as a mix of visual (diagrams), reading, and videos/audio can really help with onboarding. Different people learn better with different methods, and different methods work better in different contexts, for example I personally hate sitting at my desk watching a video, but enjoy doing so on my phone while commuting. [1] https://abbycovert.com/stuck/ https://abbycovert.com/stuck/ [2] https://www.learnupon.com/blog/multimodal-learning/ https://www.learnupon.com/blog/multimodal-learning/
- stetrain 3y agoDefinitely agreed. I have found diagrams, and tools that let me edit them quickly, to be great "state trackers" in design and planning meetings. You can get consensus, keep track of the decisions that were made, and then have a shared model you can use to coordinate building that plan. This has value even if the diagram is immediately obsolete and discarded once the project is complete.
- samsquire 3y agoI've had the idea that graph diagrams (including architecture diagrams) can be paged - you show a different set of links/vertices on each page of the same graph (show the same node but different enumeration of edges). Many codebase visualisations I've seen were too complicated to understand because the diagrams were so large. (I've seen some visualisations generated from code that were so small when panned around you have to zoom in. It's not a great experience.) I once wrote some tooling to generate Graphviz diagrams of RabbitMQ topic architectures based on log data by querying Elasticsearch to reverse engineer our architecture transitions between microservices, to see how the system actually worked in the present. My dream is that software architecture can have a late binding and can be transformed easily and trivially, without breaking any of its items it arranges. I am satisfied that I see the question "What is the main entry point?" in this post. This is so useful. I like the idea of an "entrypoint" folder for main(), routes and dependency injection containers. I think clear push/pull, async/synchronous, simultaneity and data flow can go a long way to understanding an architecture. I want software architecture to be a function of scaling requirements, that you can scale up and down. "architecture(scaling-requirements)" Wouldn't you love to be capable of changing the diagram to move code around? (You're in effect moving control flow or what I call the "tip of execution" by drawing lines or moving boxes around) I think your software architecture is a data structure, excepts it's really painful to change.
- Veuxdo 3y ago> I've had the idea that graph diagrams (including architecture diagrams) can be paged - you show a different set of links/vertices on each page of the same graph (show the same node but different enumeration of edges) You're describing something very similar to Ilograph[0] with its multiple perspectives. [0] https://app.ilograph.com/demo.ilograph.Ilograph/Request https://app.ilograph.com/demo.ilograph.Ilograph/Request
- mcbutterbunz 3y ago> I've seen some visualisations generated from code that were so small when panned around you have to zoom in. It's not a great experience. I would love a Google-Maps-Like architecture diagram. Zoom out and you see high level flows, zoom in and you get the details you want to see. Different overlays to let you explore how systems are connected or how certain sub features work. Obviously this is hard to do and even harder to maintain but it could be really cool.
- jrimbault 3y agoI failed a number of technical interviews because I can't make architecture diagrams. I come out of the first tech interview, coding/debugging, with praises. But then comes the second, the architecture interview, and I can't for the life of me draw the architecture of anything. I don't know how people learn to do that, I've learned to code/debug by being obsessive about it. But I don't see how that happens for system architecture. I've never used diagrams in my day-to-day work, so when it comes up in interviews I'm always surprised.
- sarchertech 3y agoDo you know how to design systems, and you just can’t draw them? Or do you need to learn how to design systems. If it’s the former, just practice drawing something you’ve designed with boxes, labels, and arrows. I’d it’s the latter I’d recommend https://www.goodreads.com/en/book/show/54109255 https://www.goodreads.com/en/book/show/54109255 as a good intro to the kind of “systems design” they do in interviews.
- kzhen 3y agoHi jrimbault, article author here, like any skill this needs to be developed. As sarchertech says if you already know how to design systems but struggle with the drawing then practice is the key. When I started out the diagrams I produced were messy and not very presentable, but I kept refining them. Take the opportunities you have before you, for example, if you're building a system at work then take some time to try and draw up some architecture diagrams and run them by some people who you think will give you good feedback. Then keep refining them. If it's the later then there are some videos on youtube that introduce the C4 model - the key thing is to pick a method and try to stick with it, whether that is c4 or arch42 etc, try to learn the underlying principles and apply them.
- politician 3y agoThe ask is to flatten a multidimensional space into a 2D plane, so out of the gate you're going to have problems. A really good architectural diagram doesn't have a lot of crossed lines, but you can only really do that when you have a small number of nodes or when the dataflow is broadly unidirectional. The interview is inherently unfair - when you use a drawing tool to build diagrams the work is iterative, but erasing marker during an interview looks like you've made a mistake. Start with a small top-level diagram, then build a hierarchy of increasingly detailed diagrams. Use the opportunity to steer the interviewer ("which area would you like to see in more detail?"). It also helps to have an understanding of how small bits of code map to graphical sketches, so that you can compose them later. Also, keep in mind that issues like poor handwriting and sloppy lines are exacerbated by large detailed diagrams.
- numbsafari 3y agoThese are great. You can include them in GitHub-flavored markdown files and they work. For a long time they were pretty broken, but they are looking much better supported now. https://mermaid.js.org/syntax/c4.html https://mermaid.js.org/syntax/c4.html https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/ https://github.blog/2022-02-14-include-diagrams-markdown-fil...
- politician 3y agoOne of the areas I would like to see addressed in guidance for drafting both architecture diagrams and specifications is in the documentation of the basis for design decisions. Which risks catalyzed a particular design or approach on a particular feature and to what degree? In my own work, when I need to revisit a spec months afterwards, I often have trouble because I've forgotten parts of the context that I had at the time the spec was drafted. The situation is a bit like the Chesterton's Fence where the original person that set the fence in the middle of the road has also partially forgotten why it needs to be there. It was so obvious at the time... Do others supplement their architecture diagrams and specifications with a cross-refenced list of risks, alternatives, and probabilities?
- kzhen 3y agoHi, article author here, we supplement our architecture diagrams with Architectural Decision Records (ADRs) https://github.com/joelparkerhenderson/architecture-decision-record https://github.com/joelparkerhenderson/architecture-decision... in the ADR we capture: - options considered - pros/cons of different options - chosen option - who was involved in making the decision there are a few other fields like component, product etc these are very useful for capturing decisions and something I should have mentioned in the article.
- avs733 3y agoIn my prior experience (inside and outside of software, anything having to do with a process) I think there is another situation where diagrams are enablers that they missed. Finding consensus on how the thing currently works. When these issues are takled about in words, through code, through hand waving whatever - I have experienced that the details often mask ensuring that everyone is on the same basic page. Often when there has been confusion it has taken someone pulling the group back and noting that 'Bob things A is connected to B and then connected to D but Alice thinks A connects to C before connecting to D" Just putting a architecture diagram of a process up helps find shared understanding.
- deleted 3y ago[deleted]
- 123pie123 3y agoi always make diagrams even for very basic ideas - it helps you to explain and it also helps you to confirm your ideas
- nextworddev 3y agoWhat are your favorite diagram tools? Looking for excalidraw alternatives with good Cloud resource icon support
- vidoc 3y agoThe only 2 techs I use for stuff like that are Asciiflow https://asciiflow.com/#/ https://asciiflow.com/#/ Dot https://graphviz.org/ https://graphviz.org/
- DenisM 3y agoLucid Charts
- stetrain 3y agoAt the moment I have been trying out FigJam, mostly because in an org that already uses Figma it's convenient and doesn't require another signup, account, or subscription. It's not particularly targeted at software diagrams, but when diagramming for and during planning and design meetings I prioritize quick buildout and editing over conforming to any particular standards or iconography.
- artur_makly 3y agohttps://VisualFlows.io https://VisualFlows.io it is 100% free - and we offer all AWS, GCP, and Azure icons, or just add your own via drag n drop. Sample UML: https://app.visualsitemaps.com/user_flows/share/e64da8ed-2efb-4b82-bc44-64a0ba5db32e?s=eyJ6b29tIjowLjQ1NjYyMDk0NzMwNjc3ODc3LCJwb3NpdGlvbiI6WzExNy4wNzY4Njk2NTUwNjUzMSwzMDMuNzI0MTMxNTY1NjYyOV19 https://app.visualsitemaps.com/user_flows/share/e64da8ed-2ef...
- oaiey 3y agoThe "Sample UML" is no UML. My apologies for being rude but this is not a component diagram nor any other standardized UML diagram. UML components have a visual indicator (to not confuse them with classes), use ports and connectors are consistently applied and do not vary just because the node is a S3 bucket or whatever. It is a valid diagram helping understanding something and the tool seems awesome but please do not pitch this as "Sample UML"
- vaughan 3y agoCode should generate diagrams automatically as you write it. Then you can see the complexity increase as you go, instead of looking back on a tangled mess.
- commandlinefan 3y agoI've worked with documentation auto-generators before, and the problem they have is that they can't figure out which references are relevant and which aren't. I remember auto-generating a class diagram of a Java project in the late 90's and it showed every class having a reference to the class "java.lang.String". Generators have gotten (a little) smarter with one-off heuristics like "treat the class String as if it were a primitive", but they're still way more cluttered than a knowledgeable human would ever come up with.
- kgilpin 3y agoWhat we do with appmap.io is to depict only your own code and not dependencies. Also, each diagram depicts a runtime trace and not just static imports. It produces a more focused diagram, and it also clearly illuminates factors like HTTP client and server requests, and SQL, that static analysis can’t see. The data can be depicted as a dependency map, sequence diagram, detailed trace, and flame graph.
- SkyPuncher 3y agoHow do you do that with disparate, disconnected systems?
- vaughan 3y agoParse all the code with tree-sitter[1]. [1]: https://tree-sitter.github.io/tree-sitter/ https://tree-sitter.github.io/tree-sitter/
- Supermancho 3y ago> Code should generate diagrams automatically as you write it. That's fine for some purposes, but for general discussions around many subjects (project planning, security, integration testing, etc) you won't get there from generated diagrams out of some code in an application.
- buro9 3y agohttps://c4model.com/img/c4-overview.png https://c4model.com/img/c4-overview.png That's what the argument is... and I'm in favour, there used to be such great architectural tools that were mostly UML but they did this well. I miss Visio, it was awful but everyone used it and it improved communication. I feel Google Suite is missing an equivalent, it's now draw.io, there's a real gap here.
- dragonwriter 3y ago> I miss Visio, it was awful but everyone used it and it improved communication. Did it go somewhere? (I generally prefer more declarative diagramming now — mermaidjs is my go to — but Visio is still around and widely used.)
- buro9 3y ago> Did it go somewhere? Lost it's ubiquity. There was a period in which you could rely on almost everyone to have it, which made it an attractive, convenient and low friction way to share diagrams that people could edit and update.
- amanzi 3y agoI do architecture work here in NZ and Visio is still ubiquitous here - it's part of the standard design/architecture toolkit. Usually the only discussion is whether you need the Pro or Standard licence (Pro is typically only required to integrate with external data sources).
- plaguuuuuu 3y agoit's hard to describe visio as low friction :S
- hbcondo714 3y agoThere is still no desktop version of Visio for macOS https://support.microsoft.com/en-us/office/use-visio-on-a-mac-b3c71884-5464-45b3-b664-12a1f0b84913 https://support.microsoft.com/en-us/office/use-visio-on-a-ma...
- hitchstory 3y agoArchitecture diagrams are great and do indeed enable better conversations. They are just expensive to build, expensive to maintain and go out of date fast enough that they're practically ephemeral.
- Veuxdo 3y ago> They are just expensive to build, expensive to maintain and go out of date fast enough that they're practically ephemeral. I agree with this if you're using drag-and-drop diagramming tools. Diagrams-as-code is a potential solution IMO: https://www.ilograph.com/blog/posts/its-time-to-drop-drag-and-drop-diagram-tools/ https://www.ilograph.com/blog/posts/its-time-to-drop-drag-an...
- steve_adams_86 3y agoI’m a fan of systems where the diagram and code can be changed on both sides, too. Though they lack flexibility and require a sort of convention or framework to bind both sides. Often they can work incredibly well but tend to have a narrow use case. Something like XState and the Stately studio editor comes to mind; it’ll generate state machine diagrams from code or vice versa. But it only manages state charts. I’m not sure how you could create something similar with more broad applications. Though, maybe that’s not necessary or necessarily a good idea anyways.
- kandros 3y agoI’ve used old xstate visualizer (like 4 years ago) as a communication tool to review flows with domain experts before implementing something, made conversation and spotting problems so easy
- pnathan 3y agoAlso, in order for them to capture appropriate granularities of detail, they take a lot of time and conversation with readers. I usually go with as little graphs as possible and prefer to write text; it can capture more, better, faster, and be more iterable. For specific areas like state machines or packet sequences I will drill into graphical representations more but otherwise... eh. Text wins.
- glonq 3y agoI documented the architecture of my previous project using C4. It worked well, especially because they had templates available for draw.io which is my preferred tool for diagrams. And I agree that having way more C4 examples of real-world projects would be very useful!
- p10r 3y agoHttp4k, a http library for Kotlin, has an, in my opinion, great way of generating documentation for you [0]. They explain it in more detail in their talk [1] and also have an example repository [2], if you favor to look at code. [0] https://www.http4k.org/blog/http4k_v5/#tracerbullet_a_brand_new_way_of_getting_test_feedback_and_documenting_your_systems https://www.http4k.org/blog/http4k_v5/#tracerbullet_a_brand_... [1] https://www.youtube.com/watch?v=CrslqbMbaD8 https://www.youtube.com/watch?v=CrslqbMbaD8 [2] https://github.com/http4k/exploring-the-testing-hyperpyramid https://github.com/http4k/exploring-the-testing-hyperpyramid
- jimmychoozyx 3y agoTLDR: Water is wet. Sky is blue. Grass is green.
- kannanvijayan 3y agoI find architecture diagrams particularly useful for interviews of high-level candidates. I'll structure the first half as an informal conversation where I pick up some technical work they've done and get them to talk about it in depth. The second half is usually explaining the 10kft and 1kft arhitectural overview of our product. However, I find that pre-prepared architecture diagrams are not that helpful in this case. I just open up an excalidraw tab, screen share, and sketch out the diagram in real-time, explaining things as I go along, and trying to elicit conversation about the design. I do this because my biggest challenge when tackling new work is not necessarily the code, but the context of it. Where does this live? Where does it receive its inputs from? Where dose its outputs go? How are all of these things organized into the bigger picture? What gets persisted? What's transient? A good grasp of overall architecture allows you to produce your own heuristic for how to navigate the code, where to look for problems, build internal models of where things might be going wrong, etc. The sketches get thrown away each time. The process of drawing it out and explaining it is the value.
- ShadowBanThis01 3y agoYour approach sounds like what I’d expect for an experienced hire. Good for you. Sadly, it’s not what I’ve experienced lately.
- jameshart 3y agoI think there is something to the fact that drawing the diagram in front of someone - the performance of drawing - communicates something in itself. The way you place boxes initially to set out spatial relationships. The direction in which you draw the arrows. The speed at which you draw them - clearly and deliberately, or swiftly and as an aside. The things you drew and then had to erase and redraw bigger. The way you're able to augment the diagram as you go to elaborate on or clarify your audience's points of confusion. All of that is part of what you're communicating when you draw a diagram in front of someone. None of that is part of what you capture in a static diagram in an architecture document. That's one reason why I suspect that the diagrams in documentation shouldn't necessarily look like the ones you draw in a collaborative session.
- ehnto 3y ago
- jhund 3y agoI've been using https://structurizr.com/ https://structurizr.com/ to automatically generate C4 diagrams from a model (rather than drawing them by hand). It works well with the approach for written documentation as proposed in https://arc42.org/ https://arc42.org/. It's very easy to embed a C4 diagram into a markdown document. The result is a set of documents and diagrams under version control that can be rendered using the structurizr documentation server (for interactive diagrams and indexed search). I also use https://d2lang.com/ https://d2lang.com/ for declarative diagrams in addition to C4, e.g., sequence diagrams and https://adr.github.io/ https://adr.github.io/ for architectural decision records. These are also well integrated into structurizr.
- noxvilleza 3y agoRecently been doing the same Structurizr consolidation since amongst our various teams we had a mish-mash of Lucidchart, Miro, and other collaborative design tools. One thing I was experimenting with (read: struggling with!) was a way to keep per-service (per-repo) architecture workspaces which are also synchronized on-commit to a central workspace and used !include to bind them together. The moving parts are not difficult - but writing your DSLs in a way that can handle this can be. This idea would let individual projects be self-sufficient and generate their own README doc diagrams as part of their own build process; but also have a central site which shows all the services as well as inter-service connectivity. Did you ever consider https://github.com/avisi-cloud/structurizr-site-generatr https://github.com/avisi-cloud/structurizr-site-generatr to bring together your ADRs in with your architecture, or do you keep them separate?
- jhund 3y agoI looked at the avisi stucturizr-site-generatr, however, decided to render the docs via structurizr-lite. It provides better interactivity for C4 model diagrams, e.g., drilling down into diagrams and tooltips. I found the ADR integration in structurizr-lite sufficient.
- jeazy 3y agoI strongly recommend appmap.io .. literally just go see for yourself.
- flarg 3y agoI know I'm old guard but uml worked well for me.
- stetrain 3y agoThere's some discussion here about linking diagrams to code or vice-versa. And while that's useful for documenting code already written, where I personally have found diagrams to be the most useful is in the planning discussions before and during writing the code in the first place. A room full of people can talk about things for hours without making progress, but as soon as you starting moving boxes and arrows around on a screen suddenly people have more targeted thoughts about what they agree with or what should change. The diagram is useful for planning the extend and structure of the work to be done, and coordinating the team that is building it to make sure we have a shared mental model. Once that project is done, the diagram is likely already out of date. No plan survives contact with the enemy and all that. But for this use case its job is complete and it can be discarded or archived with the rest of the planning work. Diagramming for long term documentation is a slightly different use case, and for that I tend to agree more with documentation that at least lives with the code and can be updated alongside it, manually or automatically. I just personally haven't worked in orgs large enough to pay off that level of investment.
- jacurtis 3y agoYes, yes, a thousand times yes! I have been trying to enforce this concept inside of my current organization. There is the saying that a picture is worth 1,000 words. I would extend that, suggesting that a diagram is worth well over 10,000 words. As an example, we had a project at work that kept getting thrown on my desk and every time it showed back up I would respond back with 20 questions based on limited writeups and JIRA tickets. Each time it would come back, I would get more confused, my team got confused, the architect was confused. Everyone was on different pages. Then finally, we brought a new technical project manager onto the project (at my bequest to the CTO) and within a week that TPM created a diagram, we have one 30-min meeting where he presented the diagram. We then realized that each team was on completely different pages with what needed to be built. Everyone asked a few questions, but there were far fewer questions than earlier because many of the questions were answered by the diagram. We then built out the solution 3 weeks later. So we spent 10 weeks spinning our wheels, building, unbuilding, rebuilding, and being confused as we all tried to get in alignment. THen one diagram and a 30 minute meeting later and we all left understanding exactly what we needed to do, we were all in alignment on the project and we were confident in what we needed. It also helped us call out things gaps in the initial solution, which we probably never would have identified until we ran into the problems when following the earlier method. One diagram can save HOURS (even tens of hours) of time for everybody. It reduces errors and misconfiguration and aligns teams. Diagrams are your best friend. No matter how simple something is, I always make a diagram.
- ShadowBanThis01 3y agoAn article about diagrams that doesn’t show a single one. Huh.
- abra0 3y agoWhat are the tools people use to draw diagrams? I've tried many things and settled on Miro on an iPad (infinite canvas + pencil), but I still think this space is underinvested in. The downside of diagrams from code is the loss of the wysiwyg aspect -- I want to be able to manipulate things visually.
- foobarian 3y agoI like Gliffy built into Confluence because it's default at work. I also like excalidraw and was hoping to test the collaborative feature for video calls. I think the ephemeral nature of the diagrams is just fine, it's essentially a whiteboard with some QoL features like persistence, pre-population, and undo/redo.
- artur_makly 3y agohttps://VisualFlows.io https://VisualFlows.io sample architecture: https://app.visualsitemaps.com/user_flows/share/e64da8ed-2efb-4b82-bc44-64a0ba5db32e?s=eyJ6b29tIjowLjQ1NjYyMDk0NzMwNjc3ODc3LCJwb3NpdGlvbiI6WzExNy4wNzY4Njk2NTUwNjUzMSwzMDMuNzI0MTMxNTY1NjYyOV19 https://app.visualsitemaps.com/user_flows/share/e64da8ed-2ef...
- afarrell 3y agoCell phone camera on a little holder pointed at a piece of paper. Then I join as a second participant, mute it, and turn the volume off. Or ipad and apple pencil on google docs jamboard using Duet to sketch things out.
- nucleardog 3y agoThe one issue I’ve found is that most services seem to retain _much_ less precision for participant video versus screen sharing. Text can often become really blocky and blurry. I did something similar, but used OBS. There are a few ways to feed video from a cell phone into it. Gives you the chance to do any zooming/cropping/etc to account for limitations in where you can place the phone. As well as adjust brightness/contrast/white balance if you’re really anal about that kind of stuff. From there I open the feed in a “projector” window and screen share that.
- jedberg 3y agoAn article about architecture diagrams without a single example?
- Yeroc 3y agoRelevant quote from the article: "The lack of real-world examples available - this obviously isn’t a limitation of the model itself but rather due to the fact that companies don’t want to advertise their architecture in detail in public."
- jedberg 3y agoSure, but if you're going to extol the virtues of architecture diagrams, it would help to either find one good one or make one up.
- kens 3y agoYou probably want https://c4model.com/ https://c4model.com/ which explains what a C4 architecture diagram is. (See the first footnote in the article.)
- milesward 3y agoNo discussion of architecture diagrams is complete without the widest one ever: http://awsofa.cloud http://awsofa.cloud Thanks to Leo Z for keeping this online! [edited to fix link]
- paulddraper 3y agohttp://awsofa.cloud/ http://awsofa.cloud/
- moribvndvs 3y agoI introduced C4 into my org a few years ago after disparate and unfocused documentation (if there even was any) and a lack of organizational competency on our own systems. We’ve found that you get a lot of value out of the first two levels of C4 alone. If your shop is good at UML and keeping it up-to-date, awesome, that work snaps right in as the additional layers. But whether you do 3 and 4 or not, context and container give everyone a lay of the land in easy to digest, progressive glimpses. Plus, the approach is so simple you can use it in whiteboard sketches, back of the napkin, or whatever you’ve got. Personally, I use PlantUML with a plug-in for your IDE of choice to author our formal artifacts. Excalidraw for doing it during real-time collaboration sessions. All of this is free.
- MrJohz 3y agoI found my big problem with C4 was that it was too rigid to get the architecture quite right, so I ended up either with a diagram that felt overall too low-level (because I'd had to drop down a level to get the relevant details in), or a diagram that was too high level (where I'd just skipped the bits that were with discussion, and now needed to add more written documentation to make up for it). I really like diagramming, and I tend to do it whenever architecture comes up, but the best tools I've found are just pen and paper (or pen and whiteboard, or in a pinch Microsoft Paint). That way, you can draw exactly the relevant details for the discussion at hand. This doesn't work great for "diagrams as code", i.e. anything you want to check into git. I've recently had some success with ASCII drawings - there are a couple of online tools that draw the basics, and you can get the fine details by hand - but that's more time consuming, particularly for quick sketches.
- Onawa 3y agoI had the same issue as you with C4, and d2 was the perfect balance of simple enough for creating diagrams almost at thinking speed, but with enough features (and growing) that I have been very pleased with it.
- moribvndvs 3y agoI can see having to swap back and forth between levels to pull up technical specifics as mildly annoying. I guess I’ve gotten used to it, either way having a source of truth that multiple roles can consume has been worth it in my org. If you have smaller or less complicated systems, or your audience is smaller or all peers, then I could also see C4 as having fewer benefits.
- tetha 3y agoMh. I'm not dealing in software architecture and much rather infrastructure architecture. But it's great to see that the onboarding documentation I'm currently writing Is mirroring the C4-architecture to a decent degree. Like, at the highest level, we have the different nomad clusters with stuff around them, and how these are used at a business level, relevant regulations and such. This splits into a number of identically structured datacenters with a number of connections between them. Then, each datacenter consists of a number of software clusters, some deployed, some not deployed. It's pretty much the same code with the same toggles, just somewhat different due to different underlying cloud providers. What clusters are deployed or not deployed is a risk-management-decision, as well as a business decision. But that's when the highlevel overviews stop, because then you get into the weeds. And not just a little bit, that's when you need chops to manage postgres to manage some of those clusters. But I'm putting a lot of hope into these diagrams and explanations for onboarding new colleagues, or maybe presenting the infrastructual ideas at meetups or conferences. Nothing against them, but a lack of an abstract understanding of a few high level ideas is really hurting a few new colleagues. Like, if I have a ticket, what set of systems would be right to work with? What happens if the ticket specifies ... other systems? What if you follow a runbook and the runbook suddenly banks portside really hard and tells you to touch systems outside the cluster you're working upon? In most cases, this is going to be wrong. It might be hard to determine what would be correct here, but with a decent grasp, it usually ends up easy to determine if the path isn't correct.
- quickthrower2 3y agoGood cookie banner system. Basically text at the point of needing a cookie instead of a popup regardless.
- simonjgreen 3y agoIs there something along the lines of C4 that is biased towards systems and infrastructure? Eg SaaS architecture, PaaS components, or pluggable architecture? (I suppose you could use the first 2 or 3 layers of C4)
- gardenhedge 3y agoThe real key for diagramming is representing your system from different views - this is what c4 promotes. But I don't believe you need strictness - use whatever diagramming tool you want, include whatever layers are useful to you and your team, etc.
- frozenport 3y agotoo long didn't read, no diagrams
- babblingfish 3y agoHi @kzhen, did you use a template for your website? Which template did you use?
- turdprincess 3y agoIt’s crazy to me that in todays remote first climate, many engineers still can’t effectively make diagrams without an actual whiteboard and marker. A great way to stand out as a senior contributor is to get the hang of using a virtual diagramming tool, both for design documents and live discussions.
- dboreham 3y ago(article with no diagrams)
- kzhen 3y agoHi, article author here, the reason this post has no diagrams is because it isn't about how to draw C4 diagrams but rather about some of the benefits I've found being able to refer to them in different circumstances. Given the traction this post has received I'm thinking of doing a follow up and try to explain the process I've gone through to build the ones my team uses. Would that be useful for you?
- malablaster 3y agoHow does this post have no diagrams?
- kzhen 3y agoHi, article author here, the reason this post has no diagrams is because it isn't about how to draw C4 diagrams but rather about some of the benefits I've found being able to refer to them in different circumstances. Given the traction this post has received I'm thinking of doing a follow up and try to explain the process I've gone through to build the ones my team uses. Would that be useful for you?
- jeazy 3y agoI strongly recommend appmap.io The most useful feature I have found is the request recording which is pretty much instantaneous and outputs an array of beautiful diagrams of your application code: sequence diagrams, dependency maps, flame graphs, and very in-depth After reading most of the replies here I will say that while there are some great products made and in the making, appmap crosses off a lot of boxes when it comes to a developer driven tool. We plan to use this as the catalyst for onboarding developers into the complex world that is fintech, where encryption and abstraction drive product and productivity. having setup different models and pocs using this tool myself as well as platform and staff engineers have been impressed. It even logs the data so there’s something for the data scientists to gain from the work of this tool as well. Most importantly the dev team currently grinding the gears on this thing are very responsive and as an early user I’m impressed! I found an issue and in the slack community they monitor we’ve logged and found multiple ways to overcome obstacles. Definitely recommend it. Especially for devs who are onboarding and managers with new devs they’re onboarding.
- jameshart 3y agoI feel like C4 tries to be a common language for back-of-the-envelope sketches, which is a laudable goal. UML tried to be a formal standard for back-of-the-envelope sketching, which was lunacy. But if we can all agree on basically what we're drawing, that'd help, surely. But C4 seems almost too lightweight to merit a name. Its drawing toolbox is just boxes, arrows, stick figures and datastore, with 'boxes' meaning one of four different things depending on the diagram level (Context, container, component, code). But the boxes are the easy part! The only thing I want a diagramming standard to settle on is 'what do the arrows mean, and which direction do they go in', and C4 fails on that front - the arrows mean 'whatever you label them to mean' - they are literally just 'relationships', so on one C4 diagram you might have one arrow that means 'writes data to' and another one that means 'is written to by', and that's fine. The C4 docs say little of relationships, apart from, 'Try to be as specific as possible with the label, ideally avoiding single words like, "Uses".' The C4 examples contain lots of relationships labelled as 'Uses'. So I'm sorry, but I just don't see the value C4 brings to the table. Do I need to pay for the training?
- simon_brown 3y ago> But C4 seems almost too lightweight to merit a name. Fun fact ... it actually didn't have a name for the first few years, and was just the approach I used and taught people on my software architecture workshops.
- necovek 3y agoI'll go on a limb and share a counter-point for why I struggle with diagrams: it's anecdotal but might help someone else accept that diagrams are not for everyone. As someone with aphantasia, they don't help me memorize relationships, so to get them into my working memory, I have to translate a diagram into bullet points: it's so much easier just to start with those bullet points of what components we've got, what they consist of and what relationships they have (you know, just like code itself). And having done theoretical (read: abstract) maths too, that's good enough for me to work with complex and intricate relationships. I still understand that it's not like that for most everybody else, but for some minority of us, they are just a bad way to write text/thoughts out as the graphical layout has no benefits. Yes, you do learn to read and create them, but it's an extra effort that you do for others' benefit.
- DrDroop 3y agoI think I am a highly visual person but I don't like diagrams either. There is a somewhat interesting historical irony around the development of architecture as in how this word is meant in IT and what a real architect does. The famous gang of four design patterns book got it's name from a book by the architect Christopher Alexander called a Pattern Language. This book advocates using textual description for user requirements like "I want to be able to drink my coffee in the morning and watch the sun rise". It sort of constrains the layout of the house but it still leaves a lot of room to move things around.
- 1d22a 3y agoInterestingly, as someone with aphantasia they're absolutely critical for me - because I'm not able to visualise the relationships without a diagram in from of me to "see" (This was the same for me with more abstract undergraduate maths, too). Given just the bullet points I find it hard to conceptualise the relationships between them without quickly forgetting the points I'm not directly loooking at. I echo your point that diagrams are not the solution for everyone (and that a multimodal representation of relationships is clearly best), I just find it fascinating how even with something as specific as aphantasia, there is still so much variability as to how it's experienced.
- rpbiwer2 3y ago
- kgilpin 3y agoAre there any tools that will go from a whiteboard sketch to a format like Mermaid, PlantUML or even SVG (as boxes, lines and text)? I assumed that with the AI revolution /s there would be such a thing but I haven’t found it…
- VerminOctopus1 3y agoI should probably learn C4, however, I’ve been having a great time just drawing arrows between squares with draw.io, labelling things as I see fit, without any real ruleset. This is how I generally design any larger feature and present it to the team. It seems to be well received, and being able to reference the initial architecture diagram when I want to remember how some particular system works is extremely useful. I think these diagrams risk becoming impenetrable and unpleasant to work with if they become too beset with rules and arcane visual language (see UML).
- nuker 3y ago[flagged]
- SnowProblem 3y agoIf C4 is new to you too, I recommend their intro video: https://www.youtube.com/watch?v=x2-rSnhpw0g https://www.youtube.com/watch?v=x2-rSnhpw0g. It feels like a very light ruleset over what we would do naturally when explaining a system to another engineer. That's great. Some of the ideas that stood out were: 1. Allow flexibility in the notation (shapes and color) as long as the abstractions are good. 2. When drawing arrows, make them unidirectional to show the main intent. 3. Hide details to express the main story (@ 27min in the video) 4. Don't just give names to components. Give short descriptions too. 5. Don't document the lowest levels. Code is better here.
- ElFitz 3y agoI’ve had some interesting results using GPT4 to generate mermaid diagrams from descriptions of my architecture or processes. Plus, the output being code, it’s easy to fine tune when the inevitable mistake creeps in every once in a while. It’s funny. I have never documented anything so thoroughly. It was just too time-consuming. Now I do. In part because I know there will be a diagram to complement it and improve the likelihood any of it will prove useful to someone at some point. But also because keeping said documentation and diagrams up to date will be easier.
- amanzi 3y agoI've been using ChatGPT to generate PlantUML diagrams with great success. If the diagram doesn't look right, it means I haven't been able to describe the solution well enough in the prompt. Repeating the description in the prompt until I get it right means that I can can practice explaining the solution in a way that helps me describe the solution to humans too.
- ElFitz 3y ago> I can can practice explaining the solution in a way that helps me describe the solution to humans too. That too. Also had some interesting results asking it to rephrase, structure and improve whatever description I’ve written for the process I’m documenting. Especially when my description felt more like some rambling than some clear and precise unambiguous explanation. Also a great way to generate, and more importantly keep up to date, short and concise overviews, for both technical and non-technical stakeholders.
- jheriko 3y agoconversations between idiots will remain idiotic. your abstract syntax tree is bad and you should feel bad.