Excalidraw is my favorite drawing tool for diagramming, by far. I even embedded it directly into an app so you can draw labels for buttons.
Ask HN: Visualize Software Architecture/Concepts
11–20 of 21 posts
Re: Ask HN: Visualize Software Architecture/Concepts
#12Explain it in terms of paper forms and bureaucrats. You've got a form that gets submitted, and replies come back in other very structured forms.
Your API is the person who handles the form. Just ride that analogy, and you should do fine.
Re: Ask HN: Visualize Software Architecture/Concepts
#13https://c4model.com/
https://en.wikipedia.org/wiki/C4_model
Level 1: System context diagram
Level 1, a system context diagram, shows the software system we are building and how it fits into the world in terms of the people who use it and the other software systems it interacts with.
Level 2: Container diagram.
Level 2, a container diagram, zooms into the software system, and shows the containers (applications, data stores, microservices, etc.) that make up that software system. Technology decisions are also a key part of this diagram.
Level 3: Component diagram
Level 3, a component diagram, zooms into an individual container to show the components inside it. These components should map to real abstractions (e.g., a grouping of code) in our codebases.
No need to go deeper considering your audience.
Re: Ask HN: Visualize Software Architecture/Concepts
#14C4 modelling (with associated diagrams using whatever tools) can be powerful, part of the value is that they help capture the nested and relational nature of many software systems.
Re: Ask HN: Visualize Software Architecture/Concepts
#15Excalidraw is my favorite drawing tool for diagramming, by far. I even embedded it directly into an app so you can draw labels for buttons.
Love Excalidraw - simple to use.
Re: Ask HN: Visualize Software Architecture/Concepts
#16Re: Ask HN: Visualize Software Architecture/Concepts
#17Do they really need (or care) to know the underlying architecture? Typically the non technical audiences I've worked with care more about how it solves their problems, how much it costs, who responds when something goes down (and how long it takes), what your pros and cons are compared to the competitors, etc. They typically glaze over at the architecture part or take a picture of it and send it to the devs afterward.
Why do they need to know what an API is, rather than what your integration will do for them and how it works with their existing system and process? That kind of stuff belongs in the appendix, at a very high level of abstraction (ie your software sits here, ours is here and connects to it, this is your workflow before and after). If you're going into C4 territory and explaining your whole stack, that's probably way too much detail that's not relevant to them and also may change later anyway. My 2c is to focus on the what and why, less so the how. Tell them their devs can reach out to you separately for a technical deep dive if they need it.
Re: Ask HN: Visualize Software Architecture/Concepts
#18Write a code base scanner that traces source of all identifiers.
This can generate data flow diagram.
Run the scanner across codebases, you get entire distributed software's flow.
There will be loose ends because of urls formed from configurations. It's fine, make it work, then improve.
Re: Ask HN: Visualize Software Architecture/Concepts
#19Re: Ask HN: Visualize Software Architecture/Concepts
#20Do they really need (or care) to know the underlying architecture? Typically the non technical audiences I've worked with care more about how it solves their problems, how much it costs, who responds when something goes down (and how long it takes), what your pros and cons are compared to the competitors, etc. They typically glaze over at the architecture part or take a picture of it and send it to the devs afterward…
The problem is that the non-technical people are working as architects.