Introduction
Software architects are constantly challenged by two competing forces: speed and quality of execution. On one hand, start-ups and scale-ups expect architects to make fast architectural decisions, often documented through artifacts such as RFCs or ADRs. On the other hand, large and mid-size tech companies expect architects to make strategic, long-term decisions that position the company for success over the next five years or more.
This trade-off between speed vs quality of execution shows up in software documentation, diagrams, evaluation matrices, and roadmaps that engineers and stakeholders rely on. That’s where ChatGPT can really add value as an architect assistant.
In this article, we’ll share five practical ways software architects can leverage ChatGPT. 👇
1. Technical Design Document (TDD)
A TDD is the “How” document that engineers and architects create for their product and engineering teams. It is the blueprint for how a system or feature should be built. The goal is to flesh out details of the proposed technical solution and any required architectural changes. For architects, TDDs are essential to create alignment among engineers, product managers, and other stakeholders around the “How” before implementation. Since architects may need to produce multiple TDDs, writing each one from scratch can be time-consuming. ChatGPT can help by drafting a structured document quickly, allowing you to refine and use it instead of starting from scratch.
Imagine you were assigned a new project to reduce the latency of a critical system (e.g., a ticketing system). You have a conversation with the product stakeholders and review a product requirements document (PRD). As the architect, you begin drafting a design proposal and need a document to write down your options and research. Your first starting point is ChatGPT.
Here’s a ChatGPT prompt to generate TDDs. 👇
🤖 Prompt
“You are a world-class software architect with deep experience in designing scalable, production-grade systems that adapt to evolving user requirements. You excel at creating clear, reusable architectural artifacts that other architects can readily use for their own contexts.
Create a technical design document (TDD) for the following project [system/feature name]. The document should have the following requirements at the top [core requirements]. Structure the document to include clear placeholders for: Introduction, High-Level Architecture, Detailed Design (including data flow and component interactions), Implementation Phases, Timeline, Risks & Mitigations, and Future Considerations. Ensure the document is generated in [format].”
Here’s an example TDD for project “Reducing the Latency of a Ticketing System”:
2. Architecture Decision Records (ADRs)
An ADR is a structured document that records important architectural decisions, along with their context, date, and consequences. For example, choosing between a SQL solution (PostgreSQL) vs a NoSQL solution (MongoDB) is a decision that should be recorded as an ADR. ADRs provide valuable context for engineering teams and prevent decisions from being lost in Slack threads or old emails. For architects, they make decision history transparent and defensible. This is incredibly useful for onboarding engineers to understand the sequence of changes introduced in the architecture they’re maintaining. ChatGPT can generate templated ADRs so you can focus on evaluating trade-offs rather than formatting documents.
Imagine you are the architect for a new team tasked with building a web crawler system for the data science team to use in LLM fine-tuning. You will need to make critical decisions about how the architecture should be designed from the ground up, as well as how it should evolve in terms of scale (e.g., increasing the number of distributed workers) and reviewing data lifecycle policies (e.g., how long to store the raw data and when to move it to cold storage). To communicate these decisions (and have a changelog for future revisions) you decide to create an ADR table.
Here’s a ChatGPT prompt to generate ADRs. 👇
🤖 Prompt
“You are a world-class software architect with deep experience in designing scalable, production-grade systems that adapt to evolving user requirements. You excel at creating clear, reusable architectural artefacts that other architects can readily use for their own contexts.
Create a new architecture decision record (ADR) for project [project] that covers the context, status, data, and the consequences of the chosen approach. Format it as a table entry in [format] according to the standard ADR template.”
Here’s an example ADR output below:
3. C4 Diagrams as Code
The C4 model provides a way to visualise software architecture at multiple levels of detail: context, container, component, and code. For example, you might create a Context showing how an e-commerce platform interacts with payment gateways and shipping services, or a Container illustrating how the web app, API, and database communicate. Defining these diagrams as code using tools like PlantUML or Mermaid makes them version-controllable, easy to update, and reproducible. For architects, C4 diagrams ensure that visual documentation evolves alongside the system and keeps all stakeholders aligned. ChatGPT can generate structured diagram definitions as code, which is especially useful if you already have a sketch and want to quickly turn it into a C4 diagram! We covered examples of this in an earlier post, LLMs for creating software architecture diagrams.
Say you are the architect working on a new project to build personalised product suggestions for a banking system (e.g., credit cards) based on customers’ financial history. You can begin drafting the architecture using the C4 Model (via code), starting with the Context view (showing how the recommendation system interacts with core banking systems) and moving down to the Container and Component view (designing databases schemas and APIs).
Here’s a ChatGPT prompt to generate C4 code. 👇
🤖 Prompt
“You are a world-class software architect with deep experience in designing scalable, production-grade systems that adapt to evolving user requirements. You excel at creating clear, reusable architectural artefacts that other architects can readily use for their own contexts.
Generate [Mermaid/PlantUML] code for C4 model diagrams for [system name]. Start with a Context diagram showing the system boundaries, main user types, and external systems it interacts with. Then create Container diagrams and Component diagrams for [specific service/area], highlighting key containers, their responsibilities, and interactions. Clearly represent relationships, dependencies, and responsibilities. Ensure the diagrams are structured and easy to edit for maintainability.”
4. Technology Evaluation Matrix
Architects are often required to make critical technology choices for their engineering teams. These choices can be for databases, web servers, caches, frameworks, or cloud services. A technology evaluation matrix provides a structured way to compare options against criteria such as performance, scalability, cost, and reliability. Architects typically prepare this document as part of a spike to explain and justify decisions and align stakeholders. The challenge is that creating and maintaining these matrices can be time-consuming. ChatGPT can help by quickly generating comparison tables, scoring rationales, and even preliminary recommendations and research, giving you a solid baseline to refine with your expertise.
Documents that have a technology evaluation matrix are extremely valuable for engineers and product managers when making “buy vs. build” decisions. They also document why certain technology choices were accepted or rejected based on multiple business factors (e.g., the company is willing to purchase more expensive technology in exchange for reliable service and support). Architects can use ChatGPT to generate this table via a single prompt.
Here’s a ChatGPT prompt to generate evaluation matrices. 👇
🤖 Prompt
“You are a world-class software architect with deep experience in designing scalable, production-grade systems that adapt to evolving user requirements. You excel at creating clear, reusable architectural artefacts that other architects can readily use for their own contexts.
Create a technology evaluation matrix comparing [list technologies] for [specific use case]. Include columns like performance, maintainability, team expertise, ecosystem maturity, cost, and vendor lock-in risk. Provide scoring rationale and your recommendations. Make sure your recommendations are backed by research and links to justify the scoring.”
5. Flow Diagrams / Flow Charts
A flow diagram (or flowchart) is a visual representation of a process or workflow, showing how data, tasks, or decisions move through a system. Software architects create flow diagrams to map out both happy and unhappy paths in a specific workflow (for example, the payment flow in an e-commerce application) and to highlight scenarios for engineers and product managers to follow. These diagrams help uncover (and document!) any missing edge cases before the implementation phase kicks off. Architects can use ChatGPT to quickly generate flowcharts in a code format like Mermaid to include in their design documents or TDDs.
Flow diagrams are excellent for onboarding engineers, as they help quickly identify the critical paths within the systems those engineers will maintain. A single service can have multiple flow diagrams highlighting all backend requests triggered by a single user action (e.g., what happens when a user clicks buy in your system). Architects value these diagrams and make sure to maintain them to provide clear visibility into the system’s interactions and dependencies.
Here’s a ChatGPT prompt to generate flow diagrams. 👇
🤖 Prompt
“You are a world-class software architect with deep experience in designing scalable, production-grade systems that adapt to evolving user requirements. You excel at creating clear, reusable architectural artefacts that other architects can readily use for their own contexts.
Create a flowchart in Mermaid syntax that maps out [process/workflow]. The flow should cover the happy paths [happy paths] and unhappy paths [error cases]. Include decision points for [key business rules] and show how the system handles [specific edge cases]. Ensure it is clear for both engineering and product stakeholders.”
🏁 Wrap Up
ChatGPT has increasingly become the go-to tool for software architects. It can be leveraged to quickly generate templates and documents, conduct research, and find supporting links or resources. It can also be used for brainstorming ideas and asking questions. We’ve covered five ways to create the most important resources that architects rely on in their daily workflows. With ChatGPT, architects can spend less time on formatting and boilerplate, and more time on strategic thinking and critical decision-making.
📚 Resources
- https://www.svpg.com/product-vs-feature-teams
- https://en.wikipedia.org/wiki/Scaleup_company
- https://adr.github.io
- https://www.productplan.com/glossary/product-requirements-document
- https://learn.microsoft.com/en-us/dynamics365/guidance/patterns/create-functional-technical-design-document
- https://slickplan.com/diagram/what-is-a-flow-diagram
- https://www.agile-academy.com/en/agile-dictionary/spike
- https://mermaid.js.org
