AI drafted an HLD — how do you check whether it is useful?

Tutorial 01 · about 12 minutes. Practice-inspired educational scenario. This is a model scenario, not an account of a particular client deployment or incident. Response excerpts below are editorial examples, not transcripts from a named model.

AI drafted an HLD. Is it ready for implementation?

The document looks convincing: components, a queue, a database and a diagram. That starts a useful conversation. The architect still needs to identify what came from the brief, what the model assumed and where the design could fail. A readable drawing does not establish that requirements are met.

1. Start with a brief you can inspect

Use model data. Organisation names, personal data, internal addresses and confidential documents need handling rules set by your organisation. Define the session goal: a draft for review, rather than an approved architecture.

2. Ask for questions before a solution

Separate facts, assumptions and unknowns.
List five questions whose answers would most change the design.
Explain the architectural impact of each.
Do not choose vendors or products yet.

Check whether AI asks about competing bookings for the same slot, user identification, data and retention, and availability requirements. Screen colours can wait. Mark missing decisions instead of answering on behalf of the business.

3. Draft the design and challenge it with a failure

Draft a short HLD from the brief, marking assumptions explicitly.
Compare synchronous and asynchronous email delivery.
Explain what happens when the email provider fails.
Include a simple Mermaid flowchart TB.
Do not claim that a queue alone guarantees delivery.

There is a gap: the process can terminate after committing the booking but before publishing. A queue alone does not solve a dual write. Ask AI to examine that exact gap rather than saying “improve the HLD”.

The process terminates after the booking commits to the database
but before the message reaches the queue.
What persists? What can be lost? How would we detect it?
Propose a mechanism, its costs and a verification test.

4. Fix the mechanism, not just the wording

One option is a transactional outbox: the booking and notification task are stored in the same database transaction. A separate process reads tasks, publishes them and handles retries. This is not automatically the best choice for every system; justify it against the requirement for notification loss.

Retries can deliver duplicates. Define an event identifier, duplicate-processing behaviour, retry limits and a path for manual resolution. The email provider may not support deduplication; do not promise exactly one email in that case.

5. Review the diagram separately

flowchart TB
  User["User"] --> API["Booking API"]
  API --> DB["Database: booking and outbox"]
  DB --> Relay["Task publisher"]
  Relay --> Queue["Notification queue"]
  Queue --> Worker["Email worker"]
  Worker --> Provider["Email provider"]

This is a simplified flow view. The database-to-publisher arrow represents task reads, not the database actively calling the publisher. Network boundaries and full security controls are omitted.

Check two things independently: whether the syntax renders in your Mermaid version, and whether dependencies match the text. If parsing fails, download the Markdown and preserve the original block. Provide only the diagram and parser error for repair, without a confidential brief. Ask for the same components and relationships, then render again. Changing models does not replace this check.

6. Finish with evidence and a decision

• Terminate the process between committing a booking and publishing. The task should remain recoverable.
• Disable the email provider. The booking remains valid and pending work remains visible.
• Process the same message twice. Check actual deduplication behaviour.
• Submit two bookings for the same slot concurrently. Verify the conflict rule.

Record the mechanism, rationale, alternatives, accepted limitations and verification in an ADR. The architect approves the decision; AI helps prepare and challenge it.

Your turn

In two sentences, explain why “we have a queue” does not establish reliability and which test exposes the database-to-queue gap. Then change the assumption: email must confirm a booking. Which process states now need clarification?

Try the HLD generator → · Record an ADR → · Explore resilience patterns →