Software architect toolkit - From drafting to architecture-as-code

#tooling #architecture #documentation #productivity

Sharing a small toolkit I've been using as an architect this past year, and no, it's not LLMs or anything AI related. This is purely about communicating architecture and technology better, presenting ideas, documenting it and having everything live in your version control system (VCS).

Ever since this AI (LLM) hype started, I've been playing closer and closer attention at my data and privacy. There's a clear shift happening from external services, into locally run tools.

Working as a consultant, I've often had access to services like ChatGPT, Gemini or other chat tools that help us do our jobs better, gain easier access to information, but you have to be careful not to share customer data with it, since as a consultant, it's not ours to share. Customers might or might not make these tools available to us, and in the end they decide what providers to share their data with.

So I started to think in terms of which of these tools I can run on my own machine and not have to rely on external services or websites. I'm gonna share a small toolkit that helps you progress from drafting, to modeling, to documentation and finally architecture-as-code, making it a natural part of your development process

Toolkit

I like to work with somewhat well established open source tools and standards when it comes to architectural modeling. Today, I add the requirement to be able to run them locally into the mix, so that I don't share anything to external services.

With these tools I can progress through a natural path from a draft, to modeling, documentation and finally architecture-as-code.

The tools I've stuck now with are:

Drafting

Excalidraw is a great tool for drafting out ideas, explaining stuff fast and even to give an onboarding to our systems for new developers. You can run it in a container on your machine locally and it'll always be accessible to you, even when you're not online, and I can make sure the doodles I put in there stay on my machine.

Last week I used it to explain what a chain of responsibility design pattern is and how we've used it to create an operational chain to execute specific steps in order, while also jumping into my IDE to show where the code it as, to give them a better understanding. After that I used it to explain the most important parts in RabbitMQ and what our naming conventions are and how our routing keys are constructed, to a junior architect.

Actually drawing it out from scratch while explaining it, piece by piece, helps people keep up much better than just showing a slideshow with a wall of text. If you can combine that with showing them the pieces of code in your application where the stuff is located, even better.

Modeling

Excalidraw is great for drafting and quickly explaining stuff, but I don't want my architectural diagrams to look like doodles. It also opens up the lane for everyone else to start using any tool they want to draw boxes and lines between them to describe an architectural diagram, and I would like people to follow some standards to make it easy for everyone to read diagrams in a consistent manner.

When talking about proper modeling, I use:

Draw.io
C4 model

Again, draw.io can be run in a container on your machine. Just add in the C4 model library and you can start modeling.

This is a step forward from just drafting. The reason I use draw.io is because most customers I've worked with use Atlassian Confluence as a documentation platform and it usually has draw.io installed as an extension. This way I can draw the diagram on my machine and copy paste it to Confluence and store it on a page for everyone to look at.

(I personally have a dislike for Confluence's WYSIWYG editor, so I prefer to start and nearly finalize the diagram on machine, and then move it online where it'll continue to be developed further)

C4 offers a standardized way to model out your system architecture and I've really liked Simon Brown's approach to diagrams ever since I heard his explanation that it should be like a map you can zoom in, from the top level into the code level if you want to. I can easily draw the entire system out on one map and allow developers to zoom in on the parts they like to look at, to understand what's inside them.

But, like I said, diagrams often evolve much further than initially and I also said I dislike working with Confluence, so how do we solve this?

Documentation and architecture as code

So now we get to the good stuff. What's better than writing up documentation in a platform like Confluence?

Well, putting it in your version control system is one step forward in that sense.

Documentation-as-code is not a new idea, but it is pretty rare to see it implemented in organizations. This is something I picked up from a presentation into research done at Google, and how they resolved the issue of keeping documentation up to date.

They put it closer to the developers. To the place where they actually did most of their work. Their version control system.

It has numerous benefits, including:

Versioning
Creating issues as requests or reminders to update documentation if it's out-of-date or faulty
Pull requests to offer visibility and way to discuss changes to the documentation, or feedback for improvements
Testing. You can validate your documentation, ensure links work etc. You could possibly even run spell checkers and other checks in here.
CI/CD pipelines to compile your documentation and push it to a platform that's more easily accessible to everyone in the org, and has better search

You can easily start with something like this in your repo:

    index.md
    getting-started.md
    architecture/
        overview.md
        components.md
        data-flow.md

    api/
        authentication.md
        endpoints.md

    deployment/
        docker.md
        kubernetes.md

    operations/
        monitoring.md
        backup.md

    development/
        coding-style.md
        testing.md

You can create guides for people in different roles, how to set up the infrastructure, how to get everything up and running and so forth.

Now, let's jump into the architecture part of documentation + VCS.

Architecture-as-code

So now we've added a VCS into the mix, so why not store our architecture as code? Well, luckily, people have already picked up on this with the C4 model and there are a lot of tools for it out there. The one tool I picked up recently is likec4.dev. Again, an open source tool that you can add as an extension to Visual Studio Code and you can start coding your entire infrastructure as .c4 files.

Now just slap them in a repository, write up instructions on how developers can get up and running with it, and either enable people to see those diagrams directly from your VCS, or generate them into a website that people can easily browse. The repo has you covered on that.

I've been interested in putting those up in our .NET Aspire project so people can view our system diagram when firing up their local dev environment. That would be cool!

Tip: ADRs in your VCS

Architecture decision records (ADR) are also a thing organizations definitely should use, but again, it's rare to see. You should record your most important architectural decisions, but with them I have two suggestions:

Instead of having an architectural review board, where one entity creates these records and controls them, create an architectural advice process, allowing teams themselves to propose architectural changes and gather feedback on those proposals from relevant people, such as architects, developers, designers, stakeholders and business people. This way you empower teams to think about the architecture, and not have some people be gatekeepers for it, while also getting visibility into those decisions and proper feedback.
Store ADRs in a version control system. Create ADRs in a draft state as tickets in your project management system, or as pull requests in your repository, allowing you the mechanisms to have discussions in the comment section, marking it as a 'draft', 'proposed', 'accepted', 'revised' etc. When you merge the document into the repository they are in an 'accepted' state. You get the benefit of versioning them as well. This way they're accessible for all developers to read, and they can see how those decisions went from being drafts into finally being accepted.