AI-Infused Software Architecture - Marcel Schutte

I'm trying to keep standing here, so am I loud and clear? No? A little bit? Well, I'll use the microphone. Thank you to the person in the back for the suggestion.

Well, welcome everybody to my talk on software architecture and the use of AI in architecture. I'm a lead solution architect at Society, a large consultancy company servicing all kinds of customers. For me, it's mostly government work, but we serve various industries. Twenty years ago, I started out at Society as a Java developer, and from that starting point, I worked a lot with a very different range of architects.

In those years, especially at the start, it was very much like this. Architecture was done from the ivory tower, creating very large designs and generating a lot of documentation—stacks and stacks of paper. However, over the years, it changed. We saw the emergence of new technologies, and the release cycles became faster with the advent of agile, Scrum, and DevOps. Architecture transitioned from being in the ivory tower to being much more connected to the development teams, with significantly more feedback loops that facilitated the creation of better architectures.

Well, let's get straight to it. I really enjoy using AI in my work. Please stop touching my laptop, I guess. I truly appreciate incorporating AI in my work because it can help me with the more tedious aspects of my job as an architect. I'll show you how I do that.

A little later on, I’ll even do some live prompting, so I hope everything will be all right. For me, at the core of architecture, we have the three pillars: diagrams to show the vision I want to convey to my client, documentation to demonstrate what we’ve done, and an explanation of why we’ve done it.

To me, the most important part is why. Let's see. Diagrams. I like to create diagrams on different levels because I have to convey my ideas to upper management as well as to the developers. I don't want to create diagrams over and over again, so I'm going to use a text-based tool for this, and we're going to take a look at it in a moment.

For documentation, I like to keep it concise, primarily focusing on the context in which a decision was made. It's important to keep it brief and ensure that all relevant information is included.

And the fitness function is to ensure that your architectural decisions maintain the integrity of your architecture, making sure it adheres to the principles you established at the beginning. It also facilitates the evolution of your architecture. There are three tools for this, and they are all text-based: the C4 model. Any questions?

Anyone know the C4 model? Are you creating your own diagrams, or are you creating a model where every step is a new diagram? I'll show you a nicer way to do that. ADRs—I really like to use ADRs to create documentation for my architecture, ensuring it captures the context in which the decisions were made and what other options were discussed but not used. As for fitness functions, there are many ways to implement them.

For this particular instance, I would like to focus on ArchUnit. That's a Java-based framework, and it is also available for different languages. You've got it for JavaScript and .NET. But for me, ArchUnit is a unit testing framework that actually tests your architecture, ensuring that the architecture you design is implemented correctly within the application. So, we'll take a little look at that later on.

These three things are actually perfect to use GenAI for, at least to get a starting point for your different diagrams, ADRs, and the ArchiNut code. Because, well, for C4, you've got a DSL, a domain-specific language. For ADRs, there are clear templates available, so you can use those as well. And for ArchiNut, it simply delivers code, which makes it a very good way of utilizing LLMs, since they're all text-based. Well, here's a little case study.

We're going to create something for a pizza restaurant, an Italian restaurant. It's a small business that wants to optimize its online ordering process. The current website is outdated and cumbersome, resulting in customer frustration and a loss of potential orders. We will design a simple architecture to develop a webshop for this pizza restaurant, along with additional criteria to make the ordering application user-friendly. This will simplify the ordering process and increase online orders. Before I delve into the specific prompts, I want to mention that I initially used ChatGPT for this task. However, I have switched to Claude for now because, in my experience, Claude delivers better results when prompting for code and similar tasks.

I want to give a little disclaimer. I keep it really general in this talk, and also in my work. If I use an online LLM, it's because you don't know where your data is ending up. It might work if I use an online LLM, but you still don't know where your data is going. So, I keep it general.

Write in English language. Keep it general and just fix it afterward. Well, first, let's have a look at the first prompt. Just give it some context for now. I’m a software architect working on developing new software architecture.

I need help creating a high-level structure that includes key components, their responsibilities, and interactions. Can you guide me through this step by step, tailored to modern best practices? I also like to keep asking nicely because, well, I've seen *Terminator 2*. Let's see; we can move here to Claude.

We have the same prompt that I just mentioned, just to give it some context. Now, all right, I’m going to provide a little bit of context about what I actually want to create. Let's see. I’m designing an online pizza ordering tool for a local pizza restaurant.

Here’s the text reformatted with correct capitalization and spelling: And just some basic functionality of creating a menu and placing orders. The staff in the kitchen needs to know what they need to bake, what they need to make, and also the delivery drivers need to know where they have to take the pizzas. Just a little bit of information about the techniques I'm going to use: I chose the ones I know best. I selected Java with a PostgreSQL database.

And I've actually left the front-end technology open for a later decision. I've asked him some questions about this. Let's see. He's creating all kinds of things.

I really like to use this as a brainstorming tool. He does a lot of work already. In the first instance, it helps me get an idea of what would be the best option or what could be an alternative to what I've already thought about myself. That's also why I said in the first part that AI won't replace architects; it's just the architects using AI who will make better decisions. You will have considered more options than simply recreating whatever you created in your previous project.

Because you are, well, really okay. Well, it's done. It's already created a lot of things for me. I'm not going into the whole brainstorming part right now, but it has already generated a lot of information, including some of the services you're going to need and the way you need to communicate about it, regarding your database and your authentication. From this point, you can begin the conversation on any topic you actually want to discuss, whether or not it's the best decision.

Afterward, hopefully, you will have an architecture—the start of an architecture that you can use for your system. Now, I've told you about the C4 diagrams, the ADRs, and the fitness functions. Let's have a quick look at the C4 diagrams because, for those who don't know, C4 diagrams are visual representations that allow you to zoom in on every level of your application, starting with the context diagram at the highest level. This gives you an overview of the entire context of your system, and you can dive into each subsequent level, providing more detailed information about your system. This continues until the fourth layer, which is the beginning of UML.

Basically, those are only my experiences, currently used only by developers at this point. The others are used throughout the organization. As I mentioned before, the Domain-Specific Language (DSL) makes it reusable because you create a model of your architecture. Instead of creating diagrams, you create text based on your model. You actually add your actors, your systems, and the components of those systems. You give them a name and provide an explanation of what they are doing.

And in the next part, you're going to connect those entities, basically. What I've heard a lot lately is that the architects just draw boxes and lines. These are the lines, the ones we saw before. These were the boxes. And just by adding these three, I'm going to add these three.

Well, these are actually the diagrams. What I’ve just shown you—these three, this one and this one combined with these three views—actually gives me these three diagrams. They are automatically generated from my model, so if I fill out my model completely for every component, you can actually create your diagrams by itself, which makes it really easy to reuse your model. Additionally, because it's text-based, you can easily add it to your Git repository and make it version-controlled. Let’s have a look to see if Claude can also help us with this. The diagrams include a context diagram and a component diagram. These are the first three abstraction layers of C4, with the context being the least detailed at the highest level.

In the component diagram with the most detail on the lower levels, I am asking it to actually create structured, compatible text so we can generate those diagrams. Let's see. It’s the same question; let’s see.

Let's see. Oh, we saw... Actually, he wants to help. That's cool. What he creates here are the different actors: the customer, the baker, the driver, and the pizza system at the top level, containing all kinds of subcomponents. It actually gives us some explanations of what it created on the right part of the screen.

Now, I'm not going to copy this. I've done this this morning. It actually looks like this. This is Structurizer, and it gives me all these diagrams based on the text that Claude just generated.

Basically, at a high level, we have three actors: our system and some external systems, including a payment gateway and a map service for the delivery drivers. This is what is generated initially. I really want to make sure you check what it creates, but it's a very good starting point. You already have a lot of your model completed; you just need to fine-tune it to your specific use case.

And as soon as you change your model, your diagrams will also be updated. So, you don't really need to ensure that your diagrams are always up to date. I know how it usually goes: architects create diagrams, they put them on Confluence, mostly, and then just leave them there. In this way, you can actually automate the process and ensure that they are updated as soon as you integrate it into your pipeline, making sure they reflect changes to your architecture in real time.

This is the highest level. This is just one level lower. You dive into your pizza ordering system with a web application, a staff portal, and a driver mobile app because they are on their motorcycles delivering the pizzas. Additionally, there is some extra detail on how your system is created. Afterwards, you receive more specifics for every service involved.

API Gateway. All right. Let's have a look at architecture decision records. These are the records that we keep to ensure that in the future we still understand why we made a decision.

What we put in an ADR (Architecture Decision Record) is why we did it. Not how we did it, no. It's about why we want to make the change, and we should give the several options we discussed before addressing the particular problem. We provide the context of what the problem is, and in the end, we also include the decision we've made. I really like to use a template for this.

This is a template I got from adr.github.io. They have two different ones: a small, minimal one and a slightly larger one with more options and sections to fill with your design. Decisions. Let's take a closer look at this. Well, you have done your architectural work.

# Architecture Decision Record ## Decision Title: Transition from PostgreSQL to Microsoft SQL Server **Date:** [Insert date] **Status:** Proposed **Decision Maker:** [Insert decision maker name] **Record Author:** [Insert author's name] ### Context As our project progresses into the development stage, we have identified that our current PostgreSQL database is not meeting our needs. Our requirements for performance, features, and scalability have evolved, prompting a need for a more suitable database solution. After thorough discussions and analysis among the development team and architects, we have decided to adopt Microsoft SQL Server as our new database system. ### Rationale 1. **Performance:** Microsoft SQL Server is recognized for its excellent performance in handling complex queries and large datasets. Its optimization features can lead to improved response times and an overall better user experience. 2. **Integration:** Our existing architecture utilizes several Microsoft technologies, and SQL Server will provide seamless integration with these tools, streamlining our development process. 3. **Features:** Microsoft SQL Server offers advanced features such as built-in data analysis and reporting services, which align closely with our project requirements and will enhance our data management capabilities. 4. **Support and Community:** Being a widely used enterprise-level database, Microsoft SQL Server has robust community support and resources available, which can be invaluable during development and maintenance phases. ### Alternatives Considered 1. **Staying with PostgreSQL:** While PostgreSQL offers extensive capabilities and is open-source, it was determined that it does not support some of the advanced features we require at this stage of development. 2. **MySQL:** Another popular choice, MySQL, was considered, but it lacks some of the enterprise-level features and scalability options that SQL Server provides. 3. **NoSQL Databases:** Technologies such as MongoDB were evaluated due to their flexibility and scalability. However, those alternatives do not match the relational capabilities we need for our data model. ### Implications 1. **Migration Effort:** Transitioning to Microsoft SQL Server will require data migration, which will necessitate careful planning and execution to minimize downtime and ensure data integrity. 2. **Training Needs:** Development and operations teams may require training to effectively utilize SQL Server, particularly in leveraging its unique features and management tools. 3. **Costs:** Switching to a proprietary database like SQL Server may incur licensing and operational costs that need to be accounted for in our budget. 4. **Performance Monitoring:** Post-migration, there will be a need for thorough performance monitoring to ensure that the anticipated benefits are realized and any issues are promptly addressed. ### Decision Transition the database solution from PostgreSQL to Microsoft SQL Server to better meet the project's requirements and goals. --- **Next Steps:** 1. Formulate a migration plan, detailing timelines and resource allocations. 2. Assign a team for training on Microsoft SQL Server. 3. Establish monitoring metrics to evaluate performance after migration. **Author Sign-off:** [Insert signature] **Date:** [Insert date]

Please provide the template file you mentioned, and I'll help you reformat your text according to its guidelines.

So, let's have a look at this one. I'm moving too fast because I forgot to add my address, so we're going to see the difference when I actually provide it. Thanks. I have these two templates: a minimal one and another. I want a minimal one because I've noticed how much text it's generating right now. Let's do it again. It’s actually going to use my template, which is the one I use throughout all my projects.

And it just keeps getting better. Look, it's more like this: It's just the basic start. You provide the context, considered options, decisions, and outcomes. Here, you can also change the parts you want to modify, but it already gives you a nice starting point. So it's really about using AI as an assistant rather than as someone who's taking over. In my prompt, I can't provide the complete context of my problem or define the nuances of the issues.

But it's a good starting point. Let's take a brief look at ArchUnit. ArchUnit is a utility that ensures your project's architecture adheres to the design you've created. Here, we have a simple example of a basic three-tier layered architecture.

Basically, it states that you can only move downward within the architecture. The exit is only possible from the top down, and you can only move one level lower at a time. From the controller, you can only go to the service layer, and from the service layer, you can only go to the persistence layer. You can move back up or skip a layer of your architecture. What you need for ArchUnit is to create a unit test. First, you define your different layers, and then you add a few rules that restrict access between the layers. This forms the initial setup, after which you simply enforce the rules that prevent access from one side to the other.

This is an example of this one. I've also created an architecture just now in Claude. It still knows what we created. So, what I'm going to do now is create some ArchUnit test code to ensure that I can test my architecture. Therefore, I would like you to write an ArchUnit unit test for the architecture we just designed.

The test should enforce key architectural rules, such as ensuring specific dependencies between packages or layers, validating that they adhere to naming conventions, and restricting certain components from accessing unauthorized layers or packages. Please make the test comprehensive, easy to extend, and aligned with Java best practices. Let’s see what he creates. This way, as soon as you start developing your architecture, you can already share the unit with the development team, allowing you to incorporate those elements into the test set.

So right from the start, you get a good sense of whether or not the right architecture is used in your project. It creates a very nice test set with, I think, 15 tests or something. It also describes what you are doing in those tests. These are basically the three ways I use AI in my day-to-day architecture work for now.

I hope I have shown you a little glimpse of how I use it. I also think that, in the way I use it, AI won't replace my job; rather, it really enhances what I can do and how quickly I can deliver my first design. Thank you.