AI-Assisted Design, Diagrams & Architecture Reviews

Module 1 installed the posture; this module applies it to the artifacts architects produce most: the options analysis, the diagram, the review, and the design-to-build handoff. The pattern repeats in every section — AI drafts or checks, a deterministic or documentary gate verifies, a human signs. AI-generated diagrams are plausibility machines, AI review findings run at rejection rates that demand advisory-only placement, and AI-generated IaC hallucinates resource attributes; each workflow below exists because of one of those failure modes, not despite them.

The scenario — the edge that didn't exist

The two bad edges were caught in twenty minutes because Anita read the diagram as a claim to be verified, not an artifact to be admired. Left in, the public-subnet edge would have surfaced as a security finding at review — or worse, been faithfully implemented by a build team that trusted the picture.

What You'll Learn

• Solution-options matrices at AI speedcandidate architectures and trade-off scaffolding from AI, with weights and verdicts that stay human-owned.
• NL-to-diagram with verificationgenerating Mermaid/D2 architecture diagrams from requirements, and the node-and-edge check that catches invented topology.
• Diagrams-as-code, drift-checkedthe git-native diagram lifecycle where AI regenerates from Terraform and a diff becomes a doc-drift alarm.
• Reference-architecture retrievalquerying the hyperscaler canon with citations instead of recalling it from memory.
• AI-assisted Well-Architected reviewswalking the GenAI-lens question sets with AI gathering evidence, while risk ratings stay yours.
• Design-review red-teaming, advisory-onlyadversarial failure-mode review placed so that a human triages every finding before it becomes a work item.
• IaC skeletons that survive the gatesdesign-to-build handoff code that must pass the validate→plan→policy→cost chain before anyone trusts it.

Options matrices — AI scaffolds, you weigh

The solution-options analysis (UC-02) is the first artifact of most engagements: two to four candidate architectures, compared on the dimensions that matter, with a defensible recommendation. AI collapses the scaffolding time — candidate enumeration, dimension selection, first-pass trade-off prose — from days to an hour. What it must not collapse is ownership of the weights and the verdict.

The working split, applied to an orbit-docs-copilot platform choice:

Three rules make this table trustworthy rather than theater:

• AI proposes dimensions and drafts cell prose; you set the weights. The weights are the decision — an ARB or client asking "why 30% on ops burden?" must get your reasoning, not the model's default.
• Every factual cell claim passes Module 1's checklist. Pricing shapes, regional availability, feature capabilities in the cells are the exact territory where models hallucinate. Verify against vendor docs and cite.
• The recommendation row is written by you, last. After the verified cells and your weights, the arithmetic is a starting point — the shipped verdict adds the judgment a weighted sum can't hold (team skills, roadmap risk, client politics), stated explicitly.

Loading org context into a persistent workspace (Claude Projects-class) makes successive matrices faster and more consistent — past matrices, house dimensions, standard weights become retrievable context rather than re-invented structure.

Diagrams — generation, verification, and drift-checking

Natural language to diagram (UC-07) is now table stakes: Mermaid or D2 via a coding assistant, or dedicated tools of the Eraser-AI class, turn a requirements brief into a presentable diagram in seconds. The scenario showed the cost of trusting it. The verification pass is short and non-negotiable:

• Every node exists in the designno services added because they're customary; no design components silently dropped.
• Every edge is intentionalfor each arrow: does this connection exist, in this direction, in the design? Plausible-but-wrong edges are the signature diagram failure.
• Boundaries are realsubnet, VPC, account, and trust boundaries match the design, because reviewers reason about security from these lines.
• Labels don't smuggle claimsa label like "encrypted stream" or a specific SKU on an edge is a factual claim; verify or strip it.

Diagrams-as-code in git, drift-checked against IaC (UC-08) is the structural upgrade. The diagram source (Mermaid/D2/Structurizr) lives in the repo next to the Terraform. On a schedule or on every infra PR, an AI pass regenerates the diagram from the Terraform configuration and state, and diffs it against the committed diagram. A non-empty diff means one of two things — the docs are stale, or the infra changed without a design conversation — and both are findings worth a ticket. Tooling that reads live configuration is the strong anchor here: live-infra import is the most accurate diagram source precisely because it reads what actually exists rather than what anyone remembers.

A worked prompt for the drift check, run by a repo-aware assistant (Claude Code-class):

Compare the architecture diagram at docs/architecture/orbit-docs-copilot.mmd
against the Terraform in infra/ (modules + current plan output).

Report, as a table:
1. Components present in Terraform but missing from the diagram.
2. Components in the diagram absent from Terraform.
3. Edges in the diagram with no corresponding connectivity in Terraform
   (security groups, IAM, endpoints, service configs).
4. Connectivity in Terraform not drawn in the diagram.

For each mismatch: cite the file and resource address. Do not modify
anything; this is a report. If you cannot determine a connection from the
code, say "undetermined" — do not guess.

The output is a drift report a human triages — some rows become diagram fixes, some become "why does this security group allow that?" questions. Lab 02 runs this full pipeline against a Terraform stack with three seeded mismatches; your job is to catch all three and correctly classify which side is wrong.

Reference architectures — retrieve and adapt, don't recall

Module 1 established the hyperscaler canon; this workflow (UC-09) makes it operational. All three clouds now publish formal AI reference architectures — the Azure Foundry chat baseline and AI landing zone, Google's family of five RAG reference architectures, the scenario guidance in the AWS lenses — and the corpus updates faster than memory tracks. So the working pattern is retrieval:

1. 1Load the corpus. Vendor architecture-center docs and lens documents go into a retrieval workspace (NotebookLM-class, Claude Projects, or vendor-docs MCP servers).
2. 2Query with the design constraints, demand citations. "Reference architectures for a multi-tenant RAG copilot with network isolation — cite the documents." A cited shortlist beats a from-memory sketch of last year's architecture.
3. 3Adapt explicitly. The deliverable names its base reference architecture and lists deviations with reasons — which gives reviewers a known starting point and makes your novel choices, the ones needing scrutiny, visible.
4. 4Verify the citations. Open them. A retrieval answer that misattributes guidance to a real document is this workflow's failure mode — rarer than free-recall hallucination, but not rare enough to skip the check.

For Anita, this turned a blank-page design into "the managed-RAG baseline, plus four deviations we can defend." For Rajesh, a cited reference architecture in an RFP response reads as credibility to clients who know the same documents.

AI-assisted Well-Architected reviews — the GenAI lens

Framework reviews (UC-10) are structured as question sets per pillar — which makes them the best-shaped AI-assisted workflow in this module. With the GenAI Lens (and, for agentic workloads, the Agentic AI Lens), the division of labor is:

1. 1AI walks the question set. For each lens question, it gathers evidence from the IaC, design docs, and diagrams — "is there a mechanism to evaluate model output quality?" → what the repo actually shows.
2. 2AI drafts findings with evidence links. Each candidate finding cites the file, resource, or doc section it is based on. A finding without traceable evidence is a hypothesis, labeled as such.
3. 3You validate evidence and own risk ratings. Open each citation; confirm the evidence says what the finding claims. Then set the risk rating yourself — severity in this workload's business context is architect judgment, and the division-of-labor rule from Module 1 applies to ratings exactly as it does to weights.
4. 4The review record is yours. What enters the Well-Architected tool or the client report is the validated set, in your words.

Expect the AI pass to be both generous and wrong in characteristic ways: it will surface real issues you'd have missed at hour three of a review, and it will also confidently assert findings the evidence doesn't support. Lab 01 is built exactly on this: a deliberately flawed RAG architecture with ten seeded issues, where passing means catching at least eight and rejecting the two false findings the AI asserts. Rejecting the false positives is the graded skill — accepting AI findings uncritically fails the review as surely as missing real ones.

The design-review red team — advisory only

Distinct from framework reviews: the adversarial pass (UC-11), where AI attacks your design with failure-mode checklists — single points of failure, quota and limit walls, cost cliffs, cold-start behavior, data gravity, blast radius. This is cheap paranoia on demand, and it belongs in every significant design's pre-review week.

Placement is the discipline. Evidence from AI code review shows rejection rates around 59% for AI-raised findings — a majority of what an adversarial pass raises will be wrong, irrelevant, or misprioritized for your context. Applied to design review, that dictates advisory-only placement:

• Findings enter as questions, not defects. The red-team output is a triage list for the architect, never auto-filed tickets or a gate that blocks progress on its own.
• A human disposition for every findingaccepted (with an owner), rejected (with a reason, one line), or deferred. The disposition log is part of the review record; "rejected: quota verified at N× our projected peak, see vendor doc" is itself valuable evidence.
• Tune the rubric per workload class. A RAG copilot red-team probes retrieval poisoning surface, token-cost cliffs, and eval gaps; a batch pipeline probes different failure classes. Keep per-class rubrics in your workspace and improve them after each review.
• Security and network cross-checks stay advisory too (UC-14). AI checking a design against stated posture — segmentation, private endpoints, IAM boundaries, egress paths, encryption — is a useful completeness pass, but its findings route to the security architecture function that owns threat-modeling depth. The architect's job is placing the check in the review flow, not adjudicating security depth solo.

IaC skeletons — the handoff that must survive the chain

The last artifact of the design phase is the first artifact of the build: IaC module skeletons generated from the approved design (UC-12). AI is good at this scaffolding — and research on LLM-generated Terraform (the TerraFormer line of work) documents the failure mode you must design around: models hallucinate HCL resource types and attributes, producing code that looks idiomatic and does not correspond to the provider's actual schema.

The consequence is a hard rule: generated IaC is untrusted until it survives the full chain — validate → plan → policy scan → cost check. Validate catches fabricated types and attributes; plan catches what validate can't; policy gates (Checkov-class) catch insecure defaults; cost estimation (Infracost-class) catches the skeleton that quietly provisions the expensive tier. The DevOps track owns operating that chain — your obligations as the architect are:

1. 1Never hand over unchained code. The skeleton that leaves the design phase has passed at least validate and plan; the handoff notes state what has and hasn't been verified.
2. 2Know the failure mode even though someone else runs the gates. When the chain rejects generated code, the fix conversation lands with you — "the AI invented that attribute" must be a possibility you recognize on sight.
3. 3Keep the skeleton faithful to the design. The generated code is diffed against the diagram and options record — the same edge-verification discipline as the scenario, now in HCL. This closes the loop: design, diagram, and IaC checked against each other, with drift in any pair a finding.

Where this lands in your week

• In every design reviewan AI red-team pass runs before the humans meet, advisory-only, with a written disposition per finding.
• Per options analysisAI scaffolds the matrix; you verify the cells, set the weights, and write the verdict last.
• Per diagramnode-edge-boundary verification before commit; diagram source lives in git next to the IaC.
• Per infra changethe drift check compares diagram to Terraform; a non-empty diff is a ticket, not a shrug.
• Per framework reviewAI walks the lens question set and drafts evidence-linked findings; you validate evidence and own every risk rating.
• Per design-to-build handoffgenerated IaC has survived validate→plan→policy→cost before it leaves your hands.

Your playbooks & labs

Two labs anchor this stage. Lab 01 — Well-Architected review with the GenAI lens: run the AI-assisted review against a flawed RAG architecture with ten seeded issues; catch at least eight and reject the two false findings the AI asserts. Lab 02 — Diagram pipeline: NL → Mermaid/D2 → git → AI drift check against Terraform containing three seeded mismatches; your artifact is the diagram repo plus the drift report.

Companion playbooks: pb-06 (Solution-Options Matrix with Weighted Trade-offs), pb-07 (Architecture Diagrams from Natural Language — with Verification), pb-08 (Diagrams-as-Code in Git, Drift-Checked Against IaC), pb-09 (Reference-Architecture Retrieval & Adaptation), pb-10 (AI-Assisted Well-Architected Review — GenAI Lens Included), pb-11 (Design-Review Red Team — Adversarial Failure-Mode Checklists), and pb-12 (IaC Skeletons from an Approved Design).