The Breakthrough: Architecture as Code (AaC)

CALM treats architecture like code, not pictures. But unlike previous standards (like C4) that require writing verbose JSON or YAML, the new CALM extension for VS Code lets you simply talk to your architecture.

The Workflow Kal Demoed:

1. Prompt: "Create an Order Placer service."

2. Refine: "Add a MongoDB database to it."

3. Scale: "Repeat this pattern for Order Optimizer and Order Router."

4. Connect: "Create a flow between these services."

 

Watch the AI Handle "The Real World"

What makes this demo valid for engineers is that it wasn't a rehearsed "happy path." Kal threw curveballs at the AI:

• Typos: He intentionally misspelled prompts. The AI understood the context and connected the services anyway.

• Corrections: When the AI made a "Service" a "System," he politely asked it to fix it. It updated the code and the diagram instantly.

• Complex Flows: He asked for a business flow ("Order Placer -> Optimizer -> Router"), and CALM auto-generated a Sequence Diagram alongside the block diagram.

"I’m documenting my architecture as code. I’m not documenting diagrams... I do things once and get multiple artifacts." — Kal Elsawaf

 

From "SAD" PowerPoints to Happy Devs

The highlight of the session was the automation of the SAD (Solution Architecture Description). Instead of manually pasting screenshots into a slide deck, Kal showed a Markdown file that auto-rendered the live architecture data.

• The Code: The single source of truth.

• The Artifacts: Block diagrams, sequence diagrams, and documentation tables.

• The Result: They all stay in sync automatically.

 

The ROI: Why This Matters

For Morgan Stanley, this isn't just a cool toy; it's an efficiency engine. Kal noted that he used to struggle to find time for proper architecture modeling. Now? "I raise a Pull Request (PR) or two every day because of just how easy it is."

 

Get Involved

Ready to become a "CALM-aholic"? The project is open source and looking for contributors.

• Get started with CALM in 5 Minutes

• Check out the CALM Repo on GitHub

• Watch the Full Demo on YouTube

 

Author: The FINOS Team

 

Demo Transcript

 

Khalid Elsawaf: Thanks everyone for joining us for this demo. My name is Kal, and for the last month and a half, I’m a "CALM-aholic."

[Audience laughter]

I’ve been... alright. At least I got a few laughs off of that. I’ve been using CALM now for about a month and a half in my day-to-day at Morgan Stanley. I am a lead architect for my platform. I am not a maintainer on the project—so, disclaimer: if anything goes wrong during this demo, I’m going to be pulling one of the maintainers in.

I wanted to take some time today to walk you through how I’ve been using CALM and how it has made my life a lot simpler as an architect. It’s going to be fun trying to type and use this mic, but we’ll figure something out.

Hopefully, everyone here knows what CALM is, but CALM is the Common Architecture Language Model. It’s an innovative way to express your architecture as code. When I was first introduced to it, I was like, "Well, wait a minute, we already have C4. Why do we need something else?"

There were a few things that won me over:

1. Controls: The concept of controls and being able to embed them directly into your architecture, which was something I always found missing.

2. True Architecture as Code: The diagram that is produced is one of the artifacts, but not the only artifact.

3. AI Integration: That’s what I’m going to try to demo for you guys today.

So, if all goes well, I’m not going to write a single line of JSON today.

 

The Live Demo: Creating the Model

I have an empty file. I’m going to start by asking it to create an empty CALM model. One thing I should also specify: I’m Canadian, so I feel like I have to be polite with the LLM, so please excuse me. I’m going to be saying "please" and "thank you" a lot to it.

All right, so it created an empty CALM model. You got the schema, the unique ID name, and a couple of other things. So now we’re going to have some fun with it.

I’m going to try to create just a very basic order placement system. This is not representative of anything that Morgan Stanley has—it’s a lot more complex—but this is the world I live in. So we’re going to start with that.

I’m going to ask it first to create an Order Placer service.

What it’s going to do is... if it listened to me... it’s going to create a new node, which is basically a box, called Order Placer. I meant to tell it it should be a service, not a system. Now, I told you I’m going to try to do this without writing a single line of JSON. So, now I’m going to actually instruct it to go correct it. You’re going to see later on why this is really important to be able to use the LLM instead of going in and making changes manually.

And I am Canadian, so I’m going to apologize to the LLM for making a mistake. Let's see if it's going to be polite.

All right. So, it made the change for me.

 

Visualizing with VS Code Extension

I’m going to bring up the other thing that I really like about this, which is the Visual Studio extension, which allows me to visualize at the same time that I’m making these changes. It’s pretty boring to start, but it’s about to get fun.

Now that I have a service, I’m going to add a database to it. So I’m going to politely ask it to create a MongoDB database.

[Speaker adjusts microphone and setup]

Now, if I say "keep," what should happen is... it popped up. Okay.

Now, I’m going to ask it to create a relationship between these two. Again, I’m not a maintainer of CALM, so I don’t know the JSON schema off the top of my head. Normally, I would have gone online and looked up the specs, but no, it’s 2025. We can’t do that. So, I’m going to ask the LLM to tell me what are all the different types of supported relationships.

Let’s hope it doesn’t veer off course. All right. So you see it’s telling me all the different types of relationships that are supported by CALM. I have:

• Connects

• Interacts (used to describe an actor interacting with a system)

• Deployed In (if I’m deploying it onto a platform)

• Composed Of (if my system is composed of different things)

I think "Connects" makes the most sense. And what’s really cool is it’s actually giving me an example. So I know that a Connects relationship has a source, a destination, and it also supports an interface.

So I’m going to politely ask it: Please create a connects relationship with source Order Placer and destination Order Database using the Order Database interface.

By the way, I still haven’t tried to use LLM and say thank you. Excellent. So, it created the connection for me.

 

Scaling the Architecture

For the rest of the demo, I’m going to be creating a few other things. Let me ask it to rename something. Please rename the Order Database to Order Placer Database. You’ll see why in a minute.

I want to point out something that’s actually quite cool here. Not only did it change the node that you can see, it changed the relationship. This is one of the things that's convenient about this approach because as my architecture gets more complex, it becomes practically impossible to navigate through the JSON document. But talking to the LLM is super easy.

Now I’m going to ask and try to do something complex. Please repeat this service and database pattern with the following services: an Order Optimizer, an Order Router, and an Order Capture.

Now, fingers crossed. Think happy thoughts, please. It worked on my machine this morning.

[Technical pause as the extension host is restarted]

Excellent. So, as you can see, it actually repeated the pattern. So, it created a service instance and a database instance as well as a relationship between everything. Instead of copy-pasting, I just instructed the LLM to do that and it created this pattern for me.

 

Defining Relationships and Flows

Now I want to actually create relationships between my different services. Please create the following connects relationships with the source and destination provided using the destination interface.

• Order Placer to Order Optimizer

• Order Optimizer to Order Router

• Order Router to Order Capture

I’m explicitly going to do a typo. Let’s see what it does. I think based on what it’s telling me so far, it looks like it understood that I made a typo. It did not try to create a new service for me. And so, if I press keep... voila, it connected everything together.

Show of hands: How many people have lost hours because of typos in JSON? Awesome.

Now, I want to take the next step and say, "Actually, all of these services are part of a flow." A proper business flow. So let me go ahead and create that.

Please create a flow as follows: Order Placer to Order Optimizer, Order Optimizer to Order Router, Order Router to Order Capture.

Hey, you got it right this time! See, this morning it actually made a mistake and I had to correct it. I won’t tell you what the mistake is, but I’m actually quite happy to see this.

I hadn’t shown you this before, but this is what’s actually really cool. Through this panel, I can select one of these nodes or services, and it will render that in this preview plane. So if I’m really focused on one specific thing, I can navigate through this and it’ll show me metadata about it: the unique ID, name, description, node type, and the architecture diagram.

Let me show you what the flow looks like. It’ll give me an architecture representation of the flow, but then also give me a sequence diagram.

This is one of the things that’s really cool about CALM. I don’t need to maintain different diagrams. I don’t need to use different tools or DSLs. I’m expressing my architecture as code, and it’s generating a variety of different diagrams for me. I do things once and get multiple artifacts.

Please rename Order Placement Flow to Order.

 

SAD (Solution Architecture Description)

Now I want to show you this other thing that I created which is SAD, but you’re going to be really happy when you see this. SAD is an acronym. It is Solution Architecture Description. This is something that we’ve been using quite a lot at Morgan Stanley.

I apologize in advance, I’m going to make a really horrible pun right now. We used to do these in PowerPoints, and those were very, very sad PowerPoints.

[Audience laughter]

Thank you. But now I’m actually happy to make SADs. If I flip to it, what you see is it’s just Markdown with a little bit of front matter. It’s using some widgets that we built as part of CALM. But what’s very cool is I could build out this entire document in Markdown and reference my architecture as code to fill it out.

I’m pulling in the block diagram up here, and I now have a table renderer down here with all of the different components in my architecture. And then down here, I have the flow. It’s all coming from one source.

I'm documenting my architecture as code. I'm not documenting diagrams. My architecture is in one place, I can produce multiple artifacts, and they all stay in sync. Many of us here are software developers. Software developers are really cool creatures; we will go to great lengths to be lazy, and this is a great example of that.

 

Adding Actors and Conclusion

Let me add one last thing. I’m going to add an actor—a trader—who is going to interact with this system.

Please add a Trader as an actor type. Create an interact relationship with source Trader and destination Order Placer using its interface.

Let’s see what comes out of it. One of my favorite things when I give it really long prompts is to watch this preview refresh. So much better than seeing an hourglass. Are some of you old enough to remember the old days of having hourglasses?

Okay, it looks like it got a little bit confused... Let me try that again. Create an interact relationship with source Trader and destination Order Placer.

[Adjusts prompt]

Okay, now it rendered it properly.

I’m more than happy to take questions, but the one thing I want you all to take away from this is... well, multiple things:

1. I did not write a single line of JSON.

2. I want to speak as honestly as I can: This has made my job a lot easier.

I had gone to Matt [maintainer] at one point and said I was struggling with finding time to do all of this because I’d done C4 before and I knew it takes a lot of time. I now raise a Pull Request (PR) or two or three every day because of just how easy it is.

So, I’m going to conclude all this by saying my name is Kal, and I am proudly a CALM-aholic. Thank you.

 

---