It is 3:00 AM, database connections are dropping, and the on-call engineer is staring at a diagram routing traffic through a cluster decommissioned six months ago. The diagram looked immaculate in Notion, passed review without objection, and actively lied about production topology.
Drawing boxes is cheap. Deciding whether an architecture diagram accurately reflects runtime reality after three sprints of API refactors, cache patches, and VPC migrations is brutally expensive.
When AI coding assistants entered the pipeline, drift accelerated. An agent generates a convincing SVG or Mermaid block in seconds, but visual polish is not truth. Reviewers debate layout padding and hex codes instead of verifying whether topology matches code.
I evaluated tt-a1i/archify as an external developer seeking a verifiable pipeline for AI-assisted architecture mapping. Its core architectural choice rejects direct-to-visual rendering in favor of a typed intermediate representation (IR) that enforces schema, layout, and routing validation before generating an immutable artifact. The current repository (v2.17.0-dev.1) documents integration across Cursor, Claude Code, Codex CLI, and OpenCode.[1]
The compilation pipeline enforces explicit operational boundaries:
Agent prompt or repository analysis
|
v
Typed JSON intermediate form
|
v
Schema + layout + route validation
|
v
Deterministic HTML/SVG artifact
|
v
PNG, SVG, WebM, or share-card export
Decoupling topology generation from visual presentation isolates distinct failure modes. If an LLM hallucinates a dependency, the schema gate fails. If a layout engine overlaps labels, the layout gate catches it. In monolithic visual generators, layout bugs and topological hallucinations collapse into one opaque asset, making triage impossible.
Toy tutorials stop once an agent dumps Mermaid into markdown. In production systems, reality breaks immediately:
Archify attacks this by treating authored nodes and edges as strict invariants. Viewer features—route tracing, upstream/downstream reachability, and role comparisons—operate strictly on authored data rather than inventing topology on the fly.[1]
A diagramming tool should make declared architecture inspectable. It must never fabricate runtime safety or guess network reachability.
For a global Cursor configuration:
npx -y skills add tt-a1i/archify \
--skill archify \
--agent cursor \
--global \
--copy \
--yes
For project-level discipline, commit the skill into the repository and store generated JSON alongside source code. A minimal configuration handles visual styles without mutating underlying topology:
{
"meta": {
"locale": "en",
"animation": "trace",
"visual_preset": "signal-flow"
}
}
The meta block configures presentation. It does not dictate system topology. Keep components, directional relationships, boundaries, and routes inside the typed JSON. The compiler guarantees deterministic output for identical inputs.
When prompting Cursor, constrain the model's blast radius:
Analyze this repository, then use archify to create a runtime architecture diagram.
Include:
- 8-12 core components
- one primary request path
- cache fallback behavior
- external dependencies
- trust boundaries
Use authored relationships only. Put secondary detail in component cards.
Do not infer runtime impact or merge safety.
Never inspect an unverified artifact. Validate through the compiler toolchain:
node archify/bin/archify.mjs doctor
node archify/bin/archify.mjs validate \
architecture \
examples/web-app.json \
--quality showcase \
--json
node archify/bin/archify.mjs deliver \
architecture \
examples/web-app.json \
/tmp/web-app.html \
--quality showcase \
--json
Archify runs multi-stage validation checks across JSON schema, layout geometry, HTML/SVG emission, route continuity, and label clearance.[1] The deliver command writes to the target only after every gate passes. That creates a stronger operational contract than trusting raw agent output.
File watchers that reload on every disk write introduce severe friction: an editor saving intermediate syntax wipes out working diagrams during live reviews.
Archify binds a loopback HTTP server to watch the source JSON, refreshing the rendered view only when candidate syntax passes full validation. Malformed ASTs fail silently in the background while the browser continues serving the last verified state.[1]
node archify/bin/archify.mjs preview \
architecture \
examples/web-app.json \
/tmp/web-app-preview.html \
--quality showcase \
--no-open
For pull request reviews, comparing raw diagram screenshots is useless. Archify provides structured topology diffing:
node archify/bin/archify.mjs compare \
architecture \
base.json \
head.json \
architecture-delta.html \
--json
The delta compiler isolates added, removed, mutated, and rerouted edges directly in the visual DOM.[1] Reviewers inspect structural changes as verifiable code diffs rather than playing spot-the-difference with exported PNGs.
Archify is not an unconstrained whiteboarding canvas. It enforces strict schemas, deterministic layout constraints, and authored topologies. That adds friction when you simply want to scribble a napkin sketch. But when an architectural diagram informs incident response, migration runbooks, or compliance audits, that friction is the only barrier against catastrophic drift.
The hardest operational dilemma in architecture documentation has never been how to draw components; it is whether an engineering team is willing to treat system topology as a compile-time invariant or continue accepting unverified visual folklore.
How does your team ensure production diagrams reflect live infrastructure rather than outdated design docs? Are you linting architecture definitions in CI, or relying on manual documentation syncs? Drop your setup and battle scars below.
Disclosure: Compute infrastructure and multi-model benchmark relays for this writeup are sponsored by b-lost.com — an enterprise AI gateway offering 0.8x official pricing, native prompt caching, and zero user-data retention. All benchmark metrics reflect independent reproducible testing.