Architecting a solution is not easy, and we need multiple tools to do it right. Among these tools, diagrams is an important one.

Diagrams can be used to understand something that has been built or to envision what will be built.

Whatever the situation, drawing them is a difficult exercise that takes time.

The good news is that today, with GenAI, it becomes easier to build a diagram from the code, but much more impressive, we can generate an application from a simple diagram.

In this blog post I demonstrate how to do this with a small project, and the result is already very promising.

You can replay this example on your side by following the steps below. Note that since it's GenAI, the result might look a bit different and you might not get the same fix to apply. But, give it a try, it really worth it if you like software design and architecture.

Prerequisites if you want to try it

Install VS Code:

https://code.visualstudio.com/download

Install Amazon Q Developer in VS Code:

https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/q-in-IDE-setup.html#setup-vscode

Enable workspace with Q:

https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/workspace-context.html

Install mermaid extension in VS Code:

https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid

Install AWS CDK (not necessary if you don't want to deploy the application, but only see how to generate code from a diagram):

https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html

Install AWS SAM (not necessary, only if you want to to test the original application)

https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html

Original GitHub repository

This repo contains the code you can start with. The first step will be to extract a diagram from this application code and later recreate a new application code from the diagram.

git clone https://github.com/welcloud-io/wio-amazon-q-and-mermaid-playground.git

The purpose of this application is to record feedbacks from a user and send feedback acknowledgement to the user mailbox.

The Infrastructure as Code is built with AWS SAM here, so you can test it by executing _deploy.sh in the feedback-app-project-original directory.

Amazon Q, From Code to Diagram

So the first step will be to generate a diagram from the code (I mean from all the files in my project). To do this you need Amazon Q to be aware of all the existing files in your folder. This is why you have to activate @workspace, which will index all your files so they can be retrieved when you ask a question in the chat.

The secret is that Q will not draw a diagram (like we would do on a piece of paper), I will ask Q to generate diagram with the mermaid diagram as code language. So, my diagram will be a text that I can modify in a code editor and that I can reuse as a source for multiple tools. In this case I will use it later to rebuild my project.

I tested multiple types of diagram generation, but I guess we can do much more, and better with more crafted prompts.

So, open the feedback-app-project-original folder in VS Code (File/Open Folder... menu) and follow the prompts...

Example 1: Application Diagram

Here is the prompt I used in Amazon Q developer VS Code Chat:

@workspace can you generate a mermaid diagram of my application

It took less than a minute to generate the diagram of the application.

Then I use the mermaid viewer in VS Code and... here is the result, which is correct right away.

Example 2: UML Sequence Diagram

Here is the prompt I used in Amazon Q developer VS Code Chat:

@workspace can you generate a mermaid sequence diagram of the application

Example 3: UML Class Diagram

Here is the prompt I used in Amazon Q developer VS Code Chat:

@workspace can you generate a mermaid class diagram of this application

Amazon Q, from Diagram to Code

The most impressive part is to build the entire application from the diagram itself.

I decided to start from an empty folder in VS code, so please create a new folder and open it using 'File/Open folder...' menu if you want to reproduce the example, so Q is not influenced by any context.

Step 1: Code Generation

Here is the prompt I used in Amazon Q developer VS Code Chat:

/dev can you generate application files from this mermaid diagram (I want the code of the lambdas to be written in python and the infrastructure as code with the python cdk v2)
graph TD
A[User] -->|HTTP GET /| B[API Gateway]
B -->|Invoke| C[Landing Page Function]
C -->|Return HTML| B
B -->|Return HTML| A
A -->|HTTP POST /feedbacks| B
B -->|Invoke| D[Send Feedback Function]
D -->|Write| E[(DynamoDB Table)]
D -->|Publish| F[SNS Topic]
F -->|Send Email| G[User Email]
subgraph AWS Cloud
B
C
D
E
F
end

I use the /dev agent which is an Amazon Q agent that will analyse the existing files and update them (but we have none in our case) or generate new files in our folder (that's what we want).

Note that the prompt is very short compared to what will be generated, this is where I am the most amazed, I can still not believe it worked!

Now Q starts generating code and validates that it fits the diagrams that was specified in the prompt (I guess is does a reverse engineering of its own generated code for that).

I now get code suggestions containing five new files in a folder tree, but these are not placed in my empty folder yet, I have to accept the suggestions.

It took one minute or so to get to this result, and when I click on 'Accept code' it takes about one second to create the file structure in my former empty folder.

Step 2: Test and Fix

I start first to install the requirements and make the cdk deployment.

$> pip install -r requirements.txt 
$> cdk deploy --app "python3 app.py"

And it starts to deploy 22 resources...

I thought I would have had to fix something here, but it worked RIGHT AWAY!!!

So let's go to Amazon API Gateway and copy paste my landing page endpoint in my web browser address bar to see if it works.

And this is what I get, and it works right away as well!!!

So, let's submit a first feedback now...

But this time I have a 403 error (the url access is not allowed, a common error when in fact the url does not exist in API Gateway)

Obviously the stage name (/prod in my case) is missing in the url, so let's add it, and redeploy.

I do another test, that solved my problem, but now I have a 500 error (a server side error), with this message as a response:

It turns out that the lambda function is supposed to receive an event, and this event should be in a json format.

So I ask Q to change the code of my landing page in order to send a json document instead of an HTML Form format with a new prompt in VS Code Chat. I update my code, redeploy and make a new test.

I want my feedback data to be sent as a json document to the '/prod/feebacks' endpoint with a field called "feedback" containing the feedback value typed into the html form

Ok, that works now!

I have NO error when I send some feedback, and the API call returns a 200 status

So, let's got to the DynamoDB (which has been created by the CDK code) to see if my feedback has been recorded

And boom! It is there!

I am also supposed to receive a email to acknowledge the feedback has been recorded, so I will change the destination email which contains a default value in the CDK template (again generated earlier) and I redeploy.

My user has been added and is now pending for confirmation

I confirm my subscription in my mailbox and I send a new feedback

And here is what I get straight away in my mail box!

That's it, but I think I could carry on this blog post with many other stuff I have in mind, although it's already amazing to me!

Conclusion

Diagrams can be a powerful tool to convey a vision, document and understand the structure of your software architecture.

With today GenAI tools, this is made easier, and Amazon Q coding assistant can really help you.

But, what is really new and powerful to me is that you can scaffold an entire project from your diagram.

I am not sure it's MDA (Model Driven Architecture) reshaped yet, because the problem I guess, is that if you want to make a change to your project you will have to change the diagram and regenerate things, I don't think GenAI is deterministic enough for that today (but I will try).

However, I think, it's already good for prototyping or rewriting the same small project with different technologies. For example, here I ask to use python in my code and the CDK for the IaC, but I could change my mind and use javascript and pulumi to see the differences and make my choice from there.

There would be a lot more to say about this experience, and I think it is a very simple trial with many things that would need to be improved in order to be production ready, but it's already very promising.

I think we can do much better with more crafted prompts, and that's surely what I will try to do in the next couple of weeks. It was so much fun!