DEV Community

Cover image for Open Source Project #121: archify — Natural Language to Architecture Diagrams with Theme Toggle and 4 Export
WonderLab
WonderLab

Posted on

Open Source Project #121: archify — Natural Language to Architecture Diagrams with Theme Toggle and 4 Export

#opensource #claude #agents #architecture

Introduction

"Generate beautiful architecture, technical workflow, sequence, data-flow, and lifecycle diagrams in chat."

This is article #121 in the "One Open Source Project a Day" series. Today's project is archify — an agent skill that converts natural language descriptions into polished technical diagrams, with theme toggle and crisp image export built in.

AWS

"LLM generates architecture diagrams" is not a new idea. The common problem: most implementations stop at having the LLM write SVG directly, producing results that vary in quality with every generation. archify's engineering investment is in building a complete quality pipeline: natural language → JSON IR → schema validation → typed renderer → post-render checks → self-contained HTML file.

3,464 Stars. Created April 2026. Version 2.10.0.

What You'll Learn

  • The JSON IR pipeline: why the LLM doesn't write SVG directly
  • Five diagram types and when to use each
  • How 4× native rasterization works (and why it's different from upsampling)
  • Dual-theme self-contained SVG: one file that follows the reader's color scheme
  • Semantic tech labels: how aws.lambda, postgres, kafka map to visual categories

Prerequisites

  • Basic experience with Claude Code or any AI coding agent
  • Familiarity with system architecture concepts

Project Background

Overview

archify is a cross-agent skill package. After installation, type Use archify to draw... in a Claude Code session, and the agent executes a quality pipeline that produces a zero-dependency, single-HTML-file technical diagram.

It's a fork/rewrite of Cocoon-AI/architecture-diagram-generator v1.0 (which had dark-only theme and static HTML output). The 2.x line rewrote the template around a CSS-variable theme system and added the export pipeline, typed renderers, schema validation, and post-render checks.

The README explicitly credits the original project and documents what each version adds — that kind of transparency is worth noting.

Author / Team

Project Stats

  • ⭐ GitHub Stars: 3,464+
  • 🍴 Forks: 358+
  • 📄 License: MIT
  • 📅 Created: April 15, 2026

Features

Installation 

# One command, global install, select your agent when prompted
npx skills add tt-a1i/archify -g

# Or try without a permanent install
npx skills use tt-a1i/archify@archify --agent claude-code
Enter fullscreen mode Exit fullscreen mode

After installation, just describe what you want:

Use archify to map this repository's runtime architecture.
Enter fullscreen mode Exit fullscreen mode

Five Diagram Types

Type Good for How to ask
Architecture System components, cloud resources, databases, boundaries, security groups Describe the system structure
Workflow Request lifecycles, approval flows, tool calls, CI/CD, incident response Describe participants, step order, key branches
Sequence API call chains, cache fallback, auth checks, async traces Describe who calls whom, in what order, and what returns
Data Flow Data pipelines, ETL/ELT, analytics events, PII isolation, warehouse sync Describe sources, processing stages, storage, consumers
Lifecycle State machines, order/task/deployment/agent run lifecycles Describe states, transition events, retry paths, terminal states

Example Prompts

Web application architecture:

Use archify to draw an architecture diagram:
React frontend calls a Node.js API backed by PostgreSQL and Redis,
deployed on AWS behind CloudFront.
Enter fullscreen mode Exit fullscreen mode

CI/CD workflow:

Use archify to draw a CI/CD workflow:
pull request -> tests -> approval gate -> build image ->
staging deploy -> smoke test -> production deploy, with rollback on failure.
Enter fullscreen mode Exit fullscreen mode

Data pipeline:

Use archify to draw a data flow:
Web and Mobile emit analytics events, Edge API collects them,
Consent Gate filters PII, Kafka carries accepted events,
Warehouse stores analytics tables, Feature Store derives daily features,
Dashboards and ML Model consume downstream data.
Enter fullscreen mode Exit fullscreen mode

Agent run lifecycle:

Use archify to draw a lifecycle diagram:
Agent Run starts at Queued, moves through Planning, Executing, Reviewing.
Needs Approval and Blocked are wait states.
Failed can retry. Cancelled / Expired / Completed are terminal states.
Enter fullscreen mode Exit fullscreen mode

Theme and Export

The generated HTML file has two controls in the top-right:

  • Theme toggle (Dark / Light): one-click flip, persisted to localStorage. Shortcut: T
  • Export menu: five actions (Copy PNG + download PNG/JPEG/WebP/SVG). Shortcut: E

Keyboard navigation:

  • T — toggle theme
  • E — open export menu
  • ↑ ↓ — navigate menu items
  • Enter / Space — activate
  • Esc — close menu

URL parameters (useful for automated screenshots):

  • ?theme=light or ?theme=dark — force a starting theme
  • ?openExport=1 — auto-open the export menu on load

Deep Dive

The JSON IR Pipeline: Why Not Have the LLM Write SVG Directly

This is the central architectural decision in archify.

User description (natural language)
    ↓
Agent writes a typed JSON IR (architecture / workflow / sequence / ...)
    ↓
Schema validation (bundled standalone validators, no npm install needed)
    ↓
Typed renderer (produces HTML/SVG output)
    ↓
Post-render artifact check (catches SVG errors, accidental diagonals, legend crossings)
    ↓
Deliver self-contained HTML file
Enter fullscreen mode Exit fullscreen mode

The problem with direct SVG generation:

When an LLM writes SVG coordinates directly, output quality varies per generation. Coordinate miscalculations, overlapping elements, arrows crossing unrelated nodes — these issues are difficult to solve reliably at the prompt layer.

JSON IR separates "describing content" from "layout and rendering": the LLM writes what nodes exist, their connections, and metadata; the renderer handles coordinate math and arrow routing. The LLM does what it's good at (semantic understanding, structural organization); the renderer handles the rule-based part (layout, paths).

What the post-render checker catches:

node scripts/check-render-output.mjs output.html
# or via CLI
node bin/archify.mjs check output.html
Enter fullscreen mode Exit fullscreen mode

Checks:

  • SVG coordinate values are finite (not NaN or Infinity)
  • No accidental two-point diagonal arrows
  • No arrow segments crossing the legend area
  • Elements are well-formed

When a check fails, the agent modifies the JSON IR rather than regenerating the entire diagram — so fixing a misrouted arrow doesn't accidentally break everything else.

4× Native Rasterization

Most "export diagram to PNG" implementations have a hidden defect: the scale is applied at the canvas level. A 1× image is generated and then magnified to 4×, producing blurry output.

archify's approach:

1. Clone the SVG element
2. Inline the current theme's CSS variables
   (resolve :root custom properties → write into a :root rule on the clone)
3. Set the clone SVG's width/height to "4 × viewBox dimensions"
4. Browser natively rasterizes this SVG at 4× resolution
   (vector rendering at higher resolution — not bitmap scaling)
5. Canvas sized to match, image drawn at natural size (no upsampling)
6. canvas.toBlob(mime) produces the file
Enter fullscreen mode Exit fullscreen mode

Steps 3–4 are the key: setting a larger width/height on a vector SVG tells the browser to render it at that higher resolution. This is native rasterization, not bitmap scaling — the output is genuinely sharp.

When the target resolution would exceed browser canvas limits, the pipeline automatically falls back to 3× or 2× so the export still succeeds.

Dual-Theme Self-Contained SVG

Exported SVG files are not single-theme. They embed both dark and light CSS variable sets, plus a @media (prefers-color-scheme) rule:

<style>
  :root {
    /* dark variables */
    --bg: #0f172a;
    --c-frontend: #06b6d4;
    ...
  }
  @media (prefers-color-scheme: light) {
    :root {
      /* light variables */
      --bg: #f8fafc;
      --c-frontend: #0891b2;
      ...
    }
  }
</style>
Enter fullscreen mode Exit fullscreen mode

Drop this SVG into a GitHub README and it automatically follows the reader's system color scheme. No need to maintain two images, no need for a <picture> tag with conditional sources. One file handles all cases, and it scales losslessly.

Semantic Tech Labels

Use tech labels in prompts or JSON IR and archify maps them to visual categories:

Label examples Category Color
react, nextjs, ios, browser Frontend Cyan
node, go-service, python-worker, api-gateway Backend Emerald
postgres, mysql, redis, s3, bigquery Database / Storage Violet
aws.lambda, aws.cloudfront, kubernetes Cloud / Infrastructure Amber
auth0, cognito, vault, security-group Security Rose
kafka, rabbitmq, sns, sqs Message Bus Orange
stripe, github-actions, openai, anthropic External Slate

The mapping doesn't require an icon library. Color semantics alone convey "what type of node is this" while keeping the output zero-dependency.

Workflow Diagram Structure (v2.7+)

Workflow diagrams are not general-purpose flowcharts — they're technical communication diagrams: swimlanes, semantic colors, a clear happy path, and secondary async/approval/trace paths.

Engineering constraints added in v2.7:

  • Phase headers: workflows can be organized by phase
  • Groups: nodes within a phase can be grouped
  • Exception lanes: error paths in dedicated lanes, not mixed with the main flow
  • Happy-path linting: checks that a clear main path is present
  • Same-lane orthogonal routing: connections within a lane use horizontal/vertical lines; diagonal arrows crossing unrelated nodes are rejected

Iterative Refinement

After generating a diagram, you can continue in chat:

add Redis between the API and PostgreSQL
move the auth service to the left
highlight the rollback path
Enter fullscreen mode Exit fullscreen mode

Because modifications target the JSON IR rather than regenerating from scratch, adding one node doesn't reshape the entire diagram.

CLI Tools 

node bin/archify.mjs doctor        # check environment
node bin/archify.mjs demo /tmp/out # generate sample diagrams
node bin/archify.mjs render workflow examples/agent-tool-call.workflow.json output.html
node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --json
node bin/archify.mjs check output.html   # post-render artifact check
node bin/archify.mjs examples            # list built-in examples
node bin/archify.mjs inspect output.html # view computed layout JSON (v2.10)
Enter fullscreen mode Exit fullscreen mode

archify inspect is new in v2.10: outputs the post-render layout computation, useful for understanding why a node ended up in a particular position.

Version History at a Glance

Version Key addition
v1.0 (original fork) Dark theme, static HTML output
v2.0 CSS-variable theme system, export pipeline
v2.3 4× native rasterization (fixed upsampling blur)
v2.4 Dual-theme self-contained SVG export
v2.5 Renderer-backed workflow/sequence/data-flow/lifecycle + schema validation
v2.6 Architecture renderer schema validation
v2.7 Workflow phases, groups, exception lanes, happy-path linting
v2.8 Opt-in trace animation
v2.9 Unified CLI, real-repo architecture examples
v2.10 Architecture grid placement, archify inspect, actionable validator hints

Roadmap v3.0: JSON IR stabilization — a minimal diagram.json intermediate format so Claude can make coordinate edits without drifting unrelated components, with git diff-friendly output. The Mermaid auto-parser route was cut after an experiment found it didn't produce meaningfully better output than having Claude lay out a fresh archify diagram from Mermaid input.

Resources

Official Links

Summary

archify makes a clear engineering choice about "LLM-generated diagrams": don't have the LLM write final SVG coordinates. Instead, have it write a structured JSON IR, then use a deterministic renderer for layout and rendering, and validate the output with a checker. This pipeline adds complexity but removes quality variance — the result doesn't depend on whether the LLM had a good round.

Two engineering details worth remembering separately:

4× native rasterization: by setting a vector SVG's width/height to 4× the viewBox dimensions, the browser renders it at that higher resolution natively. Exports are genuinely sharp at retina resolution, not blurry from bitmap upsampling.

Dual-theme self-contained SVG: a single file embeds both dark and light CSS variable sets with @media (prefers-color-scheme). Drop it into a GitHub README and it follows the reader's system theme automatically — no two-image maintenance, no <picture> tag.

If you regularly need architecture diagrams in documentation, PR descriptions, or Notion — and want them to look good at any resolution and in any color scheme — archify's "describe → generate → export" workflow is worth trying. One npx command installs it; Use archify to draw... in Claude Code triggers it.

Explore PrimeSkills — a curated marketplace of AI agents and skills, each validated against real enterprise workflows. No hype, just what actually works.

Visit my personal site for more insights and interesting products.

Top comments (0)