> Maybe we should write architecture diagrams using code instead. With code, we can update architecture diagrams within a pull request, version them and quickly

> Maybe we should write architecture diagrams using code instead. With code, we can update architecture diagrams within a pull request, version them and quickly modify many of them at once. For some level of granularity, you can do even better - generate the architecture diagrams from what you actually have up and running, as long as your deployment units coincide with the components. I know that Apache Skywalking isn't the most popular APM solution out there, but they have something very much like that: https://skywalking.apache.org/blog/2020-08-11-observability-at-scale/topology-v8.png https://skywalking.apache.org/blog/2020-08-11-observability-... Here's an article about it: https://skywalking.apache.org/blog/2020-08-11-observability-at-scale/ https://skywalking.apache.org/blog/2020-08-11-observability-... Better yet, these sorts of "live" diagrams also allow you to display statuses of all of the connections between the components, open related data, tracing information or even related logs, if you need to look at why a particular endpoint doesn't work as it should. It automatically updates based on how things are related and so you don't have the inevitable difference between how things are and how they should be, just because someone would have forgotten to manually change some diagram somewhere. Of course, there are downsides to this - it won't be as pretty/presentable as something that someone could create in a design tool and there's not much "customization" to speak of, that'd let you focus on the different perspectives (as exemplified in the article). However, as long as you're actually in control of your services (e.g. can instrument them), tools and approaches like this seem like sane options regardless. I'll go on a bit of a tangent here, but I'll say that diagrams are really powerful, yet people usually under-utilize them and see them as just documentation or something to tick a box. I'll use databases as an example for this, say, using tools like DbVisualizer to explore database schemas: https://www.dbvis.com/features/database-management/#explore-visualize https://www.dbvis.com/features/database-management/#explore-... While it is great, sadly, that's as far as things usually go. And yet, there's something like MySQL Workbench that lets you either generate ER diagrams from an existing DB or create your own all the same: https://dev.mysql.com/doc/workbench/en/wb-eer-diagrams-section.html https://dev.mysql.com/doc/workbench/en/wb-eer-diagrams-secti... Where it differs, however, is that it has synchronization capabilities and forward engineering capabilities: where you can either generate all of the SQL that's necessary for your schema for migrating a fresh DB to it, or alternatively point it at a live DB instance (dev/testing/...) and get the SQL scripts based on the diffs between the schemas. See https://dev.mysql.com/doc/workbench/en/wb-forward-engineering.html https://dev.mysql.com/doc/workbench/en/wb-forward-engineerin... or https://dev.mysql.com/doc/workbench/en/wb-design-schema.html https://dev.mysql.com/doc/workbench/en/wb-design-schema.html With this, your workflow can become as simple as: - generate a diagram from your dev database, change it as needed - visually validate that it looks okay (way easier to do than looking at a bunch of scripts, many are visual creatures) - if okay, generate the SQL scripts (which you can also look over), and/or test them out against your instance - if you have an automated DB migration tool, put the scripts in it Of course, it isn't perfect and won't help you in complex cases, but for trivial stuff it's still excellent without pigeonholing you into something specific (it's still SQL at the end of the day). I think that visualizations are good in most cases, whether it's an ER diagram, an architecture diagram, or something like a DAG for your CI pipelines: https://docs.gitlab.com/ee/ci/directed_acyclic_graph/ https://docs.gitlab.com/ee/ci/directed_acyclic_graph/ So why couldn't we plan out our architectures in a similar way? Where's my AWS/GCP/Azure Studio 2030, where I can draw a bunch of boxes and click either "Generate infrastructure as code package" or "Deploy to AWS/GCP/Azure live", or open already generated/running deployments in the tool to edit them?