AI architecture documentation without hallucinations

An assistant reads a Slack thread about a proposed cache and draws “API → cache → database” as the current architecture. The diagram is valid Mermaid, and the relationship looks ordinary enough to escape notice. But the cache was never approved or deployed. In architecture documentation, a hallucination is a claim like that: plausible, neatly expressed and unsupported by the system or accepted evidence. The repair is not a more confident prompt. It is an explicit source for each important node and edge, an “unknown” label where evidence stops, and human review before a draft becomes a current-state map.

Direct answer: Ask AI one bounded question, tell it which sources are authoritative, and have it list every component and relationship with its evidence before it draws anything. Let it say "unknown" instead of guessing. Then review the diagram edge by edge against the evidence, and treat the result as a draft until someone who knows the system accepts it. AI is best at drafting and at spotting possible drift, not at declaring the architecture correct.

Why AI architecture output goes wrong

• Pattern completion. The model fills gaps with what is typical: a cache, a gateway, a retry queue.
• Unbounded scope. "Document the whole system" forces the model to summarize more than it can see.
• Stale or mixed sources. An old diagram and current code disagree, and the model silently picks one.
• Clean rendering. A neat diagram makes a wrong edge more convincing than a messy one.

Model providers acknowledge the problem. Anthropic's guidance on reducing hallucinations recommends allowing the model to say it does not know, grounding answers in direct quotes, and requiring citations. It also notes that these techniques reduce hallucinations without eliminating them.

A routine that works

1. Ask one bounded question

Not "document the platform", but "draw the checkout request path from cart submit to order write, for backend engineers". Name the audience and level of detail.

2. Supply evidence and rank it

Useful inputs: README and architecture docs, service manifests and infrastructure definitions, API schemas, relevant tests, recent pull requests, accepted decisions, ownership metadata, and existing diagrams labeled current or historical. Say which sources win when they conflict, for example "code and manifests over the 2024 diagram".

3. Require an evidence table before the diagram

Before drawing, list every component and relationship as:
claim | evidence (file, message, or doc) | confidence | open question
Mark anything without evidence as UNSUPPORTED. Do not include unsupported items in the diagram.

This exposes gaps while they are still text, before they become boxes and arrows.

4. Split detection from editing

Use one pass to find likely documentation gaps, and review that list. Then run a second, focused pass to update one artifact. That is safer than letting an agent rewrite a documentation set on its own, and small changes are easier to review.

5. Review the render edge by edge

Check every arrow's direction, every boundary, every label, and the failure paths. Compare with actual behavior and with what the system owner knows. Read the source too, because a label can hide a wrong edge.

6. Keep uncertainty visible

When the evidence conflicts, do not let the model choose. Record the disagreement ("unclear whether the worker writes directly to Orders DB") and ask an owner. Documentation that pretends to be certain is worse than documentation that says what it does not know.

Check a generated relationship against its source

Suppose AI drafts “API → cache → database” from a thread that mentions a cache proposal. Before accepting the arrow, find the message that approved it and verify the deployed service actually calls that cache. If the thread only says “we might add a cache,” label the relationship proposed or remove it from the current-state view. A diagram can be syntactically valid Mermaid and still make a false architectural claim.

Draft and review the diagram in Arialine for a Slack discussion: the request, proposed change and accepted version can remain together. Ask reviewers to check each node and edge against code, configuration or an accepted decision, and write “unknown” where the source is silent. The NIST AI risk framework is broader than diagramming, but its emphasis on documented human review fits this verification step. Do not advertise a model-generated diagram as a discovered map of the running system.

Where Arialine fits

Arialine uses AI when you describe a diagram or ask for a change, and it is built so that AI output is reviewed rather than trusted:

• Pasted Mermaid needs no AI. Valid Mermaid renders exactly as written, so if you already have verified source, no model is involved.
• Changes are reviewable. In proposal mode, the channel default, an AI-drafted edit waits for Apply, Edit proposal, or Dismiss.
• Nothing is lost. Every applied change is a version. A wrong edit can be undone or rewound, and the earlier draft stays in History.
• "Why" comes from records. Asking why an element exists answers from the board's recorded history (the decision, author, date, and source message), not from an invented rationale.
• Context is explicit. AI only runs when someone invokes it, using the thread, recent channel context, or a discussion the user selects. It does not read code or infrastructure.

Arialine can still misunderstand a request or a discussion. Review generated diagrams before relying on them. Better prompts for Slack diagrams covers how to ask, and troubleshooting Mermaid in Slack covers what to do when the source is invalid.

Use a claim-to-evidence ledger

For each generated statement, record the claim, source, reviewer and disposition: confirmed, corrected, unknown or removed. NIST's AI Risk Management Framework treats validity, reliability and transparency as properties that require governance and measurement, not a promise produced by the model.

Prefer repository files, deployed configuration, service catalogs, incident records and accepted decisions over conversational memory. When sources conflict, show the conflict instead of asking AI to choose silently. Keep generated prose and diagrams in draft until a responsible owner checks the relationships that affect security, operations or customer data.

Next step: sample ten claims from one AI-generated document and require a source or an explicit unknown label for each.

FAQ

Can AI generate architecture directly from code?

It can infer structure, but code does not reveal intent, external agreements, runtime configuration, or operational reality. Treat the result as a draft and compare it with what the owners know.

Should AI write ADRs?

It can draft one from an accepted decision. A person must verify the context, the alternatives, and the consequences before it is recorded.

What is the strongest use of AI here?

Finding possible drift, turning a verified description into Mermaid, and making repetitive edits, with a person accepting each change.