How to use AI to generate software architecture diagrams from simple prompts

In a previous post, I shared some of my experience adding AI features into this proof of concept application I've been building entirely with AI coding assistants. This weekend, I found a way to break through the obstacle I faced with attempting to use Gemini to generate images through its Imagen API. A much simpler way to realise my goal of getting an AI to generate architecture diagrams from a simple prompt, is to instruct the LLM to produce Mermaid diagrams.

All it needed was a carefully crafted system prompt, instructing the AI to create the Mermaid diagram syntax from the data model, and voila! We now have a way to generate almost any diagram one can think of. 

Take a look at this video:

And here's built-in native features of the app that shows different Mermaid diagrams for the system under inspection:

Play with the app here
Source code
Project Wiki

Demonstrating the power of bulk changes to delivery plans

So I've added some bulk operations to the SMT app.

Bulk AI Agent Scenarios (Macro Operations)

Empower the agent to perform complex, multi-entity updates that are tedious to do manually. Each plan highlights the scope before execution (e.g., “This will affect 12 teams...”).

1) Capacity & Resourcing Manager

• User intent: “Reduce all teams’ capacity by 20% to account for burnout.” / “Set everyone’s AI productivity gain to 15%.”
• Tool: bulkUpdateTeamCapacity (supports capacityReductionPercent, aiProductivityGainPercent, avgOverheadHoursPerWeekPerSDE, plus filters by teamIds or orgIdentifier).

2) Strategic Portfolio Manager

• User intent: “Move all ‘Low ROI’ initiatives to the Backlog.” / “Approve all initiatives under the ‘Cloud Migration’ goal.”
• Tool: bulkUpdateInitiatives (criteria: goalId, themeId, roiValue, confidenceLevel, status, isProtected).

3) Scope Trimmer (“Haircut” Tool)

• User intent: “Reduce the scope of all committed initiatives by 10% to fit the plan.”
• Tool: bulkAdjustInitiativeEstimates (adjustmentFactor scales SDE-year assignments; same criteria options as above).

4) Org Restructurer (Advanced)

• User intent: “Move all teams from John Doe to Jane Smith.”
• Tool: bulkReassignTeams (moves all teams from one SDM to another).

Safety checks

• Bulk operations can be destructive; the agent surfaces an impact summary before running (e.g., “Reducing capacity for 15 teams”).
• Plans are shown to the user before execution; review the description to confirm scope.

Example scenarios

• Scenario A: “Austerity” Plan — “Increase overhead to 10 hours/week for everyone and move all ‘Low’ confidence initiatives to the backlog.”
  • Plan: bulkUpdateTeamCapacity({ avgOverheadHoursPerWeekPerSDE: 10 }) + bulkUpdateInitiatives({ status: 'Backlog' }, { confidenceLevel: 'Low' })
• Scenario B: “AI Boost” — “Assume 20% productivity gain for all teams.”
  • Plan: bulkUpdateTeamCapacity({ aiProductivityGainPercent: 20 })

Here's a transcript of the chat - using AI agent to tweak the year plan:

How AI tooling can help software engineering and product managers improve productivity

Have you ever been curious to learn how popular systems like Excel, Visual Studio, Adobe Photoshop, Call of Duty, Amazon, Uber, AirBnB, ChatGPT, Netflix, Apple Appstore, etc. are architected and built? If you're a software manager designing a technical organisation, and want to learn how the best technology teams are organized, wouldn't you like some insights into how to organize your teams, drawing on how the big tech companies do this? What about if you're stepping into product and program management, need to create a 3-Year Plan roadmap, along with business goals with metrics for Return on Investment, and have a dashboard on a single page to view overall status? What if you're a software delivery manager, and need to manage multiple delivery teams, co-ordinate the plan, identify bottlenecks? If you're a senior software leader and wish to analyse where your engineering resources are being consumed, and model capacity and hiring scenarios, wouldn't you like a tool to help provide insights? What if you received a top-down instruction to reduce headcount by 25% and model the impact on your roadmap, or you need to optimize your delivery plan based on various funding scenarios, wouldn't it be nice if you had a tool to do this quickly? If you could have a tool that lets you run scenarios and show the impact in near real-time, wouldn't that save you a lot of time? Wouldn't you like a tool that generates product and strategic narratives for you without you writing a single sentence? What if you're preparing for interviews in domains you're not familiar with, wouldn't you like a tool that could just generate you a simulated mock system so you can have rich context so you show up as prepared and more informed?

If you've answered Yes, to at least one of these questions - then you might just be interested in an app I'm POC'ing :-) Click here to learn about the app, or just click here to start playing with it.

I had some good fun this past weekend building out AI features for my app "Software Management Tools", which is currently a single page web application built entirely in vanilla Javascript/HTML. It is hosted on Github and the source code is freely available here. This tool basically allows you to do everything above and much more. All you need is a Gemini API key (free tier), to get started and experimenting. What's more interesting is that I didn't write a single line of code myself, thanks to Google's Gemini, OpenAI's Codex, Github and Visual Studio code - I've become a copy-and-paste developer. Seriously though, I do believe frontend engineers are at risk of losing their jobs to AI, and now with the concepts my tool demonstrates, the need for technical managers is also questionable! 

AI Features Implemented (Using Gemini 2.5 Flash model)

• Users can create a mock system, organisational structure and 3 year plan from a single simple prompt like "Create a spreadsheet platform like Micosoft Excel"
• Users now have access to an integrated chat assistant that has context of the data model and the screen currently selected, where they can:
• Learn more about the system architecture
• Find out about platform dependencies like AWS, GCP services
• Inspect bottlenecks in the architecture
• View, Edit, Inspect and modify organisational and team structures through the chat
• Inspect and Optimise the year plan using AI assistant
• Write up business plans and narratives for a 3 year plan
• Critique the engineering skills set, look for risks
• Tweak the capacity constraints and model different capacity scenarios - with AI-generated suggestions

Where am I going next?

The possibilities are near endless - there's so much more to explore, but I've hit the classic stage of deciding to refactor the codebase to a more modern architecture, scrap the MVP and build again. Here are some ideas I'll progress next weekend:

• Enable self-generating code contributions to the app itself
• Build richer agents to perform complex operations from the chat like 
• Reduce all teams capacity by 20% and show the updated ATL/BTL plan
• Move all initiatives under the Goal XYZ to BTL to free up capacity
• Create a new system from the chat panel - an AI-wizard
• Export the plan to Excel or Project
• Create a detailed quarterly release plan for team XYZ
• Merge these two teams into one team, reporting to a new SDM, move these services to the new team, keep remaining services in unallocated team
• etc.
• Build an appstore feature for users to share and publish their generated systems
• Build an internal app API for the app to make agent creation more accessible
• Refactor the codebase to cleanly separate out concerns - and make future porting easier
• Start building out detailed planning features
• Explore a backend-as-a-service to make simpler API key integrations possible for folks who are not software engineers

What have I learnt?

In just two days, I learnt a lot:

• How to integrate AI-features into an app, navigating the API Key challenges
• How to build a model router
• How to fine tune a system prompt for the task at hand
• How to pass JSON syntax to the LLM to model your data structure you need the LLM to return
• How to validate generated data for compliance
• How to build a chat assistant, with memory, history and context
• How to build an agent framework
• How to structure your code to make AI integrations portable and extensible
• How to build effective retry and backoff mechanisms when AI is overloaded
• How clunky the AI provider APIs are - whilst apps like ChatGPT and Gemini are multimodal, it is not as simple or clean to do this from an API, there should be a simple multi-modal API for developers, one endpoint to call - without overly complex security concerns
• How powerful and fun coding can be again!

Do you have some demos, I can't access the tool?

I thought you'd never ask. 

This video shows the AI creating a new system from prompt, using "Create with AI" feature:

This video shows using AI to inspect system architecture...

This video shows how AI can help manage product roadmaps...

This video shows of AI can assist with inspecting software delivery plans..

This video shows how managers can have fun using AI to manage their org structures...

Departing AWS: Conscience, Growth, and Work-Life Balance

I decided to feed my last blog post on leaving AWS into NotebookLM:

The provided text is an extended, introspective essay written by a senior engineering leader detailing the reasons for his resignation from Amazon Web Services (AWS) after four and a half years at the Cape Town headquarters. The author structures his departure around three core concerns: Spirituality and Conscience, particularly regarding the company's involvement in projects like Project Nimbus amid the Middle East conflict; Lack of Professional Growth, driven by structural changes within AWS and limited opportunities for promotion to director level (L8) in South Africa; and Negative Return on Investment (ROI) in Time, exemplified by increasing work hours, extensive weekend work, and compromised work-life balance, despite the financial success of his stock options. The essay concludes that the job no longer provided satisfactory personal, professional, or spiritual alignment, leading him to pursue a new role in Intelligent Traffic Systems with a local South African company.

Here's the audio generated (it got my RAGE model wrong, it stands for Reality, Aspirations, Goals, Expectations):

Here's the video generated (not bad, but it got 2023 mixed up with 2024) - but a good summary nonetheless:

Why I left AWS after 4.5 years as an L7 Senior Engineering Manager

Earlier this year, on 05/30 (this is how Amazon writes dates, 30th May) I walked out of the amazing Amazon Africa headquarters in Cape Town, after spending four years and six months, as a senior engineering leader. I'm writing this post three months after a sabbatical break, and after a week into my new job (started 09/01) in a totally different field of Intelligent Traffic Systems... 

Here's a screenshot from my LinkedIn profile on my time with AWS:

Here's a video of me from 2022:

And here's some memories from my time there. Listen, I did enjoy my time with Kumo/AWS. I met some fantastic, highly intelligent, self-driven, motivated and resilient people from diverse backgrounds, from all over the world. AWS is indeed a special place. Their motto: Work Hard. Have Fun. Make History -- is very real! For anyone considering working in AWS, go for it! But be sure to do your homework first. This is just my story, a single datapoint from 1.5 million Amazonians, and 290000+ AWS employees worldwide - and in a small pond from South Africa (SA), a sample of 1 L7 engineering leader from a pool of ±7-9 managers, servicing 250-300 software engineers across Kumo and EC2 (this alone hints at the opportunity for L8 promo in SA is very small...)

Memorable moments with my teams...

I left AWS in good standing if I decided to boomerang back, here's a goodbye email sent by my manager to 1000+ people:

Why did you leave AWS, you seem to have been on a good trajectory, yes? 

My AWS colleagues, family, friends and now too, my new coworkers asked me why I left AWS. Feelings about exiting AWS started back in Q3 2024 triggered by the events unfolding in the middle east, causing me to reflect deeply on my personal and professional aspirations critically assessing my value system, borne from my RAGE model which has been my north star for over a decade.  

It turned out that the key metric is Return on Investment (ROI) across these three dimensions: 1/ Spirituality; 2/ Professional Growth and 3/ Work-Life balance.