AI for architecture decisions: options, an ADR and a diagram

Architecture questions rarely have a “right answer”; they have trade-offs. Here AI’s biggest use is laying out options quickly and drafting the write-up of the decision. Simon Willison also says he uses LLMs at the start of a project to learn what the options are. But you make the decision, because the AI doesn’t know your team, budget and risks unless you tell it.

Step 1: Give the context in numbers

Ask “microservices or monolith?” and you get a textbook answer. Instead give your real situation: team size, technology, load and the actual problem. Then say exactly what you want.

We are two developers running an online shop (Django + PostgreSQL on one server). Before Eid we get up to 5,000 orders a day; the rest of the year about 500. The bKash payment callback sometimes arrives late. We are wondering whether to move to microservices.
1. Give 3 options, with the pros and cons of each for a team of our size.
2. Recommend one.
3. Write an ADR in Michael Nygard's format (Title, Status, Context, Decision, Consequences).
4. Finally, give Mermaid flowchart code for the recommended design.

1

Tap the picture to see it full size

1. 1Context with numbers for team, load and problem, then four requests

Step 2: Read the options and the recommendation

1

Tap the picture to see it full size

1. 1The main advice, then the three options

ChatGPT gave three options: keep the monolith and harden it, a modular monolith with background workers, and microservices. It recommends the second: not microservices yet. The reasoning comes from our context: running, monitoring and debugging separate services is a heavy load for two people, and the real problem (late callbacks) would not go away just by splitting services.

It also did a sum: 5,000 orders a day is about 3.5 orders a minute averaged over 24 hours. That checks out (5,000 ÷ 1,440 minutes ≈ 3.47), and it adds that real Eid traffic will be far more bursty than the average.

When you read an answer like this, check three things:

• Did your numbers come through correctly? Here both 500 and 5,000 did.
• Does each con fit your situation, or is it generic textbook text?
• Which questions have no answer? For example, how much load our server can take today: the AI can’t know that. A load test has to measure it.

Step 3: Fix the ADR

An ADR (Architecture Decision Record) is a short document that says why a decision was made. Michael Nygard set out its five parts in 2011: Title, Context, Decision, Status, Consequences. His reason: without the reasons written down, a newcomer either blindly accepts an old decision or blindly reverses it.

ChatGPT’s ADR has all five parts, and its Consequences list the negatives alongside the positives (the extra work of running queues and workers). That’s exactly what Nygard asked for: write down all the consequences, not just the good ones.

But one thing needs fixing. Under Status, ChatGPT wrote “Accepted”. In Nygard’s format, until the stakeholders agree, the status is Proposed. We ran this test three times and got “Accepted” all three times. Whether a decision has been made is not for the AI to say; your team decides.

Step 4: See the diagram from the Mermaid code

1

Tap the picture to see it full size

1. 1The Mermaid code: copy it with the copy button at the top

Copy the code and open mermaid.live. Clear the Code box on the left and paste; the diagram appears on the right straight away.

12

Tap the picture to see it full size

1. 1Paste the code here
2. 2The diagram appears here

Looking at the diagram, ask yourself: what happens if a callback arrives twice? What if it never arrives? Are both paths in the diagram? If not, ask ChatGPT to add them. Gaps are easier to spot in a diagram than in prose; that’s the real value of drawing it.

Sources

• Michael Nygard, Documenting Architecture Decisions (Cognitect, November 2011): the five parts of an ADR, the status rule, and listing all consequences.
• Mermaid, Flowchart syntax: the rules of flowchart code.
• Simon Willison, Here’s how I use LLMs to help me write code (March 2025): using LLMs to learn the options at the start.