Documenting architecture: Wireshark, PlantUML and a REPL to glue them all (2017)

I can think of a few use cases that aren't really reverse engineering. Documenting legacy systems that weren't properly documented up front. Documenting/identifying divergence from design time documentation. Documenting a microservice stack where each service is individually well documented but the totality is not. Generating documentation from a prototype to use a starting point for a more structured design process.

Generally, I've seen very few projects that have architecture documentation which is kept up to date past the first release. So it's not an insane idea given the on the ground reality, but yes it does seem a bit like shutting the barn door after the horse is already out.

Working in secops, we aren't always the ones building the tools, and the products we're required to support never come with this kind of documentation.

I think it's more about changing architecture and having up to date documentation.

Jeez Louise I worked with the Oracle BI stuff once and it was so poorly documented that using Wireshark was the only to figure out what all pieces did what and how it all worked. I'd imagine other such enterprisey stuff that's been hobbled together over the years through acquisitions may be similar and these companies are always rather terse or ask you to put in a ticket and wait a month to find out.

> Have systems gotten so messy and complicated that we build them without knowing they're actually doing, until after they're built?

Oh, hey, you've just practically described one popular implicit formulation of Agile. :)

Detailed and coherent design documentation is rare in my experience, even at organizations that are staffed at a level including dedicated staff ostensibly for this purpose. I can think of precisely one place I've worked for that had a design process that produced documentation effective for specifying the project ahead of time and as a reference from then on out. A culture committed to this plus dedicated technical writers who regularly met with a team of a domain expert, tech lead, and UX/UI folks for the purpose of producing project documentation helped a lot.

Other organizations may have had individuals producing documentation but it was a lossy process, magnified when they moved on from the project.

In 30 years of doing consulting on 'systems' work, it's astoundingly rare to see documentation of any sort that accurately & completely represents the current running state of the system. Sometimes it's close, but more often than not it's whatever was presented to get budget before any development has started.

Occasionally, the folks involved actually believe their doco does represent reality. They are invariably wrong, sometimes in small details, usually in large ones. Tools like this are an invaluable check on reality.

> Have systems gotten so messy and complicated that we build them without knowing they're actually doing, until after they're built?

Yes, in general, at least in my world (medium size to enterprise). Agile has made this in practice much much worse.

It is cool (compared to Visio or even Rational Rose), but it makes me wonder about the value of the diagram itself. The textual input is just as readable and takes up less space on a screen (or, God forbid, a printed piece of paper) - other than giving managers a warm and fuzzy feeling that there's a pretty picture there, why bother generating the diagram at all?

I haven’t read the source code, but I assume that it just looks at the timings of the request. After all, it’s just one user, no need to worry about 50 concurrent requests.

Weave Scope can do that: https://www.weave.works/oss/scope

Edit: Not affiliated

The bottom half of the example diagram shows traffic between the "backend" and "keycloak" that clearly isn't browser to nginx traffic.

You'd need to be running wireshark on a network interface that could see all that traffic, so yeah - sort of "at the server level" - in the sense that you'd need to be sitting on the server's network(s) to sniff that.