Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Architecture diagrams enable better conversations

unravelled.dev

Post reply on HN
Print view View original

1–10 of 141 posts

Re: Architecture diagrams enable better conversations

#2

Post by taeric »

I'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.

Re: Architecture diagrams enable better conversations

#3

Post by samsquire »

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). 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.

Re: Architecture diagrams enable better conversations

#4

Post by jrimbault »

I 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.

Re: Architecture diagrams enable better conversations

#5

Post by numbsafari »

These 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://github.blog/2022-02-14-include-diagrams-markdown-fil...

Re: Architecture diagrams enable better conversations

#6

Post by politician »

One 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?

Re: Architecture diagrams enable better conversations

#7

Post by avs733 »

In 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.

Re: Architecture diagrams enable better conversations

#9

Post by kzhen »

taeric wrote: post #2

I'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 n…

Hi 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)

Post reply on HN