THE GITHTML FIELD GUIDE
Review AI-generated architecture diagrams for invented relationships
Treat every box and arrow in an AI-generated architecture diagram as a claim. Verify that the component exists, the relationship is supported, and the direction and label mean what readers will assume. Separate current architecture from proposed architecture, and include a text explanation so the diagram is not the only source of meaning.
Choose the diagram's question
A system context diagram answers who uses the system and what surrounds it; it should not pretend to show every internal call. C4's diagram guidance helps distinguish these levels. Decide whether the draft describes ownership, deployment, data movement, or request sequence, because an unlabeled arrow can be interpreted differently in each. An attractive layout does not resolve ambiguous semantics. Record the reviewed revision and scope, including services excluded from inspection. Avoid filling an empty corner with a plausible component simply to make the diagram look complete.
Audit nodes and edges separately
For an illustrative import flow, list each node and its supporting source: upload handler, validation component, processing worker, and result store. Then examine each edge: what moves, in which direction, under what condition, and whether the handoff is synchronous or deferred. The example is a review pattern rather than a proposed system. A repository dependency does not by itself prove a runtime network call, and a configuration name does not prove a deployed service exists. Mark uncertain relationships with a textual note instead of presenting them as established facts.
- Node check: verify existence, responsibility, and owner.
- Edge check: verify direction, payload meaning, and conditions.
- Scope check: distinguish observed implementation from intended design.
Publish a usable noninteractive explanation
Write a short narrative for the main path and note the important failure boundary. W3C guidance on complex images supports providing detailed textual alternatives for information-rich visuals. Ensure the explanation remains understandable when the image is too small or unavailable. Prefer a static diagram for the core document and treat any interactive version as optional. If the HTML will be read in gitHtml, do not depend on a remote diagram renderer or enabled scripts. Ask a maintainer to review the meaning before spending time polishing colors and layout.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.