Architecture and model diffs via code conventions

As an engineer reviewing human code or AI code, the first thing I always scan a pull request for are architectural changes. Is the right code in the right place following codebase conventions? And is the domain well modelled?

I’ve never really enjoyed looking at the diff on GitHub and trying to extract this information which is buried in hundreds of lines of code. And now I don’t have to.

In recent posts I talked about strong codebase to conventions to enforce application architecture and domain modelling concepts. Those same conventions make it easy to identify architecture, and architecture changes, in your codebase. It therefore becomes trivial to add an architecture/model diff to your pull requests (all via code without any LLM involvement.)

This type of simple architecture diff gets added as a comment to every PR:

Domain-level summary

Choosing what information to display and how to display it was an intersting exercise. I had to try and reverse engineer how I think, to identify what exact information I looked for and in what order, to then build a visualisation that does that.

The first questions I want to answer are: what applications and subdomains/contexts/service/libraries are impacted architecturally in this PR and roughly how?

In this example, there are changes to the dev-workflow-v2 which is a tool, not a key part of the project. But there 8 items in the domain model of riviere-builder that have changed and that is a very core part of the project so I definitely need to investigate that.

Before looking at the code, I’ll look at the details section of the architecture diff to pick out the key changes.

When I do that, I can see that most of the changes here are related to the published language of the riviere-builder subdomain. That’s important, because the published language is the external contract of the model, the parts other subdomains and applications can couple themselves to. So these changes impact the boundary and what type of coupling is allowed in the system.

From pull request to rich visualisation

Comments in github pull requests are pretty limited in terms of what you can do and how you can make it look visually appealing and interactive. So I’m currently working on something that sits outside of the pull request, that can be added as a link in the diff comment to view a better visualiations.

I’m pretty sure this will become normal in the industry in the next couple of years and forward-thinking teams can get a sizeable advantage by investing in this now.

Generating a full inventory

In a similar fashion to diffs, I also generate an architecture and model inventory on each build (it’s called the domain guide atm). This provides a description of each subdomain, the key aggregates, and each use case.

This guide is useful to both humans and AI. At a glance you can learn about each part of the system and all the uses cases supported and the domain concepts used in each use case.

As mentioned, this is primarily the level of detail I want to work at. I want to focus on this level as much as possible and jump into lines of code where it feels necessary.

Conventions are the key for better understanding and controlling your architecture

As I said at the start, having strong conventions in your codebase makes various aspects of managing your architecture and model possible or much easier. Conventions make enforcing rules easier. Conventions make extracting architecture from your code easier. Conventions make it easy to generated diffs and other views of your architecture easier.

Conventions are effectively a metamodel for modelling your architecture. Every codebase has one, some are just more explicit and intentional than others. I do encourage you to invest in building strong and enforceable conventions. You’ll get better results with AI and you’ll have a better understanding of your architecture, domain model, and especially how they are evolving.

I do still feel that I am less connected to the domain model because I am not writing lines of code. I feel less comfortable discussion abstractions and modelling decisions with AI because the code is not embedded in my mind. But these visualisations are helping to bridge that gap, and I know they are reliable becausse they are extracted from code based on conventions that are enforced. Hallucination free.