DEV Community

Cover image for Stop Shipping Architecture Diagrams That Cannot Be Verified
linweidao
linweidao

Posted on

Stop Shipping Architecture Diagrams That Cannot Be Verified

#cursor #vscode #devtools #productivity

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
Enter fullscreen mode Exit fullscreen mode

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.

The Production Pain Point: Plausible Topology Hallucinations

Toy tutorials stop once an agent dumps Mermaid into markdown. In production systems, reality breaks immediately:

  • Stale Dependencies: An API contract shifts, but the diagram retains legacy edge routing.
  • Silent Degradation Paths: Cache-miss fallbacks disappear because the happy path was easier to summarize.
  • Drifted Assets: PRs alter ingress rules while documentation retains obsolete PNG exports.
  • Destructive Previews: A half-written JSON buffer crashes local watchers, replacing verified state with blank canvases.
  • Unverified Authority: Reviewers mistake a polished visual layout for verified runtime topology.

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.

A Working Cursor Workflow

For a global Cursor configuration:

npx -y skills add tt-a1i/archify \
  --skill archify \
  --agent cursor \
  --global \
  --copy \
  --yes
Enter fullscreen mode Exit fullscreen mode

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"
  }
}
Enter fullscreen mode Exit fullscreen mode

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.
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.

Atomic Previews and CI Architecture Deltas

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.

Operational Trade-Offs

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.

cursor #vscode #devtools #productivity

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.

Sources

[1] tt-a1i/archify README

Top comments (0)