Once upon a time, about 3.5 billion years ago in the Archean Eon, microbial mats were an early example of collaboration and division of labor between living beings. Bacteria and archaea in different layers were responsible for different chemical reactions, exchanged the products of their labor and could communicate with chemical signals.
And all was good for billions of years until eukaryotes came to be, then multicellular organisms, then nervous systems, social structures, … Life was getting better and better at managing complexity. Microbial mats weren’t — they couldn’t.
During my IT career I’ve been on countless troubleshooting calls and also heard countless “horror stories” from my friends and relatives who also worked in IT. After seeing and hearing it all, do you know what enterprise IT reminds me of? Yes, you’ve guessed it right — microbial mats! Different groups work off their own playbooks, which are often informal/tribal. Nobody has the whole picture. As a result, innovation is limited to group-level band-aiding. Some IT people justify this situation by saying that a modern enterprise is so complex that it is impossible to have a holistic view. Some others say that agile === no documentation. People want to get AI insights, but AI can’t be fed tribal knowledge.
This story outlines an approach which can be used to gradually harness complexity. I’ve been using this approach for some time and mentioned it in the “Connecting the dots” story. The approach is called “Architecture As Code”.
So, what does it mean? According to the TOGAF definition, “Architecture” is:
- The fundamental concepts or properties of a system in its environment embodied in its elements, relationships, and in the principles of its design and evolution. (Source: ISO/IEC/IEEE 42010:2011)
- The structure of components, their inter-relationships, and the principles and guidelines governing their design and evolution over time.
“As code” means treating architecture descriptions as software assets:
- Prefer text-based human-readable formats (YAML, XML, Markdown).
- Store in version control systems. Preferably with the software components they describe, where applicable.
- Use “Semantic URIs” to cross-reference model elements. Like Java does using fully-qualified names.
- Build a holistic model from multiple sources, also like Java does by loading code from multiple class files in multiple jars and then resolving references.
Human are visual creatures, they process visual information much-much faster than text — “A picture is worth a thousand words”, remember? “Architecture As Code” explained here uses Drawio diagrams (which are XML internally) and maps them to a semantic architecture model.
Demos
Before going further, let’s take a look at a few demos:
- The Internet Banking System from the The C4 model for visualising software architecture site — documentation rendered using Cerulean & Sketchy Bootswatch themes.
- Basic demo — Cerulean & Sketchy.
Applications
If you liked the demos, you may read more about how to start using Architecture As Code on the architecture model documentation site including the C4 sub-package.
The rest of the story explains where this approach might be applied and how it may evolve.
Corporations spend millions of dollars and thousands of hours on onboarding new people to development teams as well as on troubleshooting calls — I was once on a call with 200+ people, including big bosses, figuring out who was responsible for a particular database and then trying to get a hold of that person so the they could restart the database. Spending a fraction of that to produce architecture documentation — for some reason it is not done. Maybe because Visio, PowerPoint, UML tools, and corporate Wikis can’t handle the level of complexity. This is where Architecture As Code may help.
POCs and joint efforts with vendors and partners are another area — there is no underlying shared tribal knowledge, so having architecture documentation is very important. A few years ago I was on a cloud migration call with consultants from a leading cloud provider. We couldn’t make any progress and these guys were just laughing at us — they were charging by an hour!
Hackathons are similar to POCs/joint efforts, but with compressed timelines. For example, how can one do a 2 day hackathon if onboarding of a new team member takes weeks?
And finally, companies spend millions of dollars to get their people certified in, say, cloud technologies. So a person gets certified, they know a ton of methods to deploy a cloud VM. But none of them is applicable in the organization because the organization has its own way to deploy VMs. Documenting company’s “cloud technology tree” — whitelisted services and SKUs, how they are deployed — would take a fraction of certification effort and would likely make more impact on the bottom line and cloud migration timelines.
Dimensions of Expansion
Let’s say you’ve explored the demos, liked them, and started to use the C4 model to document your architectures. What’s next?
You may grow your Architecture As Code practice along several dimensions as outlined below.
Metamodels
Metamodels, like the C4 Model, define your “architecture/organization dictionary”. The C4 model has just 6 “words” — System, Container, Component, Code, Person, and Relationship. You may define your own words expanding the C4 model.
E.g. Azure Virtual Machine may extend Container and provide documentation how virtual machines are used in your organization. With Azure you don’t have to start from scratch — I have an old model which I created when I was getting ready for AZ-900: https://azure.models.nasdanika.org/references/eSubpackages/compute/diagram.html
It was mentioned above that people are visual. This is why companies like Microsoft and AWS provide icon sets to facilitate adoption of their technologies:
- https://aws.amazon.com/architecture/icons/
- https://learn.microsoft.com/en-us/azure/architecture/icons/
You may use these icons in metamodels and diagrams. Drawio comes with 2000+ icons. If it is not enough, FlatIcon, Icons8 — millions of icons (more icon sources).
Drawio libraries and templates
Once you have your metamodels, you may create and publish Drawio libraries to use in your organization and share with partners.
You may also create and publish templates.
Patterns
You may publish patterns as both libraries and templates.
Progressive elaboration — decision binding
You may publish generic patterns and templates. E.g. a template may have “Compute” and “Storage” elements. As architecture solidifies, “Compute” type can be changed to, say, Azure VM in one case and to on-prem server in another. With Azure VM you may go down SKUs adopted in your org. Every time you change the type, the help link will be updated. Consumers of your architecture wouldn’t have to have a pre-existing knowledge of what, say, B8ls v2 means — they’d click on the question mark and navigate to the org-specific documentation. E.g. they might find out that certain VM sizes are general availability, but some other require a special approval which would affect their timelines.
Integrations — loading from multiple sources
Architecture models can be loaded from multiple sources. For example, pom.xml, Java sources, cloud APIs. See “Connecting the dots” for more information.
You may implement custom integrations with your org-specific systems. For example, people directory, technology catalog, systems inventory.
Representation filtering
You may modify styling of diagram elements representing architecture elements during generation — example.
For systems under construction you may use representation filtering to report construction status — on track, behind, blocked, …
For deployed systems you may display runtime status — it might save hours and hours of troubleshooting.
Federation
Multiple models may be federated into a holistic model in the same way as Java/Maven applications are assembled from multiple modules.
Once you have a federated holistic model, you may implement semantic search/RAG on top of it.
Element level Single Page Applications
One of advantages of Object-Oriented Programming over procedural programming it its ability to “bind” context by using fields instead of passing tons of arguments.
With generated architecture documentation you may have element-level web applications operating in the context of that particular element. Semantic search/RAG would be one of examples — I may ask the same question in the context of Sign In Controller and Mainframe Banking Façade and get different answers specific to the context component.
Reporting live element status is another.
Markdown rendering
You may use org-specific fenced block processors pulling information from different systems.
You may also implement URI rewriting in links to use logical URIs instead of “physical” URLs. For example, people://joe-doe would resolve to Joe Doe page in the org directory and systems://ibs would resolve to the IBS system home page.
Generation
Architecture models can be used for generation/solution instantiation. Architecture documentation is an example of generation.
Solution instantiation may create resources and update the model with resource IDs, e.g. ARNs. Then representation filtering can be used to show status of those resources on diagrams in generated documentation.
For source files the generation process may merge generated code with hand-crafted code.
