Using Archify for Validated AI-Generated Architecture Diagrams
Better Stackgo watch the original →
the gist
Archify prevents AI hallucinations in architecture diagrams by forcing agents to output structured, validated JSON that is compiled into interactive HTML, rather than letting the model handle layout or drawing.
The Breakthrough
Archify shifts architecture diagram generation from an LLM-driven visual task to a structured data task, using a strict JSON schema and validation layer to ensure that diagrams are backed by repository evidence rather than model hallucinations.
What Actually Worked
- Agent Skill Integration: Install Archify as an agent skill to integrate directly into existing workflows like Claude Code or Cursor, allowing the agent to output structured JSON instead of raw image data.
- Evidence-Based Nodes: Attach nodes to specific code locations by including commit hashes and line ranges in the JSON, which Archify verifies to add an 'SRC' badge to the diagram components.
- Architecture Diffs: Compare two validated JSON snapshots to generate a visual diff showing added, removed, or rerouted components, which is useful for PR reviews.
- Interactive Exploration: Use the generated HTML output to click through services, allowing users to trace upstream and downstream dependencies rather than manually interpreting static arrows.
- Constraint-Based Prompting: Limit the scope of diagrams by asking specific questions, such as 'What happens on a cache miss in this service?', and restricting the output to 8 to 12 nodes to prevent the agent from generating overly complex or inaccurate maps.
Context
Developers often struggle with AI-generated diagrams that hallucinate non-existent services or produce messy, unreadable layouts. Archify functions like an LLVM for system maps, where the LLM acts as the front end, the JSON acts as the intermediate representation, and the local compiler produces the final HTML. This approach separates the system description from the visual layout, ensuring the diagram remains consistent and verifiable.
Notable Quotes
- 'The model describes the system; it does not decide exactly where every box is going to go.'
- 'A graph can be completely valid and still describe the wrong system; you still have to read it.'
- 'If you can't clearly say what question the diagram is answering, don't generate the diagram.'