A God‑Level Architecture Diagram Skill Open‑Source: Say Goodbye to draw.io

Project Overview

Cocoon‑AI released architecture-diagram-generator on GitHub, a Claude Skill that reads a textual system description and produces a self‑contained HTML architecture diagram with dark theme, grid background, and embedded SVG components. The output can be exported as high‑resolution PNG or single‑page PDF, removing the need for Draw.io.

How It Works

The skill is not a standalone application nor a VS Code extension; it is a Claude‑specific skill. Claude parses the description, injects SVG elements into a predefined HTML template, and returns a complete HTML file with all CSS and SVG inlined, requiring zero external dependencies.

Visual Specification

The template enforces a visual style: dark background (near‑black), grid texture, monospaced JetBrains Mono font, and semi‑transparent glass‑like component boxes. Colors are fixed by component type—cyan for frontend, green for backend, purple for databases, amber for cloud services, and rose for security modules. The diagram footer automatically includes three information cards summarising each layer’s technology stack.

MIT license; a fork named Archify adds a light theme and more export formats.

Function Details – “Speak Human Language to Draw”

No code or markup is required. Users can provide a natural‑language description or a component list generated from code analysis. Example description: “A React frontend connected to a Node.js backend, backend uses PostgreSQL, plus a Redis cache.” Claude generates a four‑layer diagram showing each component, ports, and arrows for HTTPS, REST API, and SQL, along with three summary cards.

Color Handling

The default dark theme uses semi‑transparent borders, and the color semantics are hard‑coded: cyan for frontend, green for backend, purple for databases, amber for cloud services (e.g., AWS), and rose for authentication/security modules, allowing instant visual identification without reading text.

Export Options

The generated HTML file includes three buttons in the top‑right corner: Copy copies a high‑resolution PNG to the clipboard for pasting into tools like Feishu, Slack, or Google Docs; PNG downloads the image; PDF exports a single‑page PDF preserving the dark theme. No command‑line tools or additional dependencies are needed—simply double‑click the HTML file.

Quick Start

Installation is straightforward: unzip the skill into ~/.claude/skills/ or a project’s .claude/skills/ directory. The author’s Claude account was disabled, so they reconstructed the skill using Codex.

Preparing a Description

Let AI analyze the codebase: feed the code to Codex, which returns a component list.

Write manually: list components and connections, e.g., “React frontend talking to Node.js API, PostgreSQL database, Redis cache, hosted on AWS.”

Ask Claude for a template: request a typical SaaS architecture diagram.

Generation Prompt

用你的架构图 Skill，根据下面的描述生成一张架构图：

[粘贴你的架构描述]

Demo with GitHub README Example

The official README description is straightforward:

- React 前端
- Node.js/Express API
- PostgreSQL 数据库
- Redis 缓存
- JWT 认证

Feeding this description to Codex returns a JSON and HTML file. The diagram shows a dark background, grid, aligned components, and arrows. The frontend box is labeled “React + TypeScript + Tailwind CSS”, the backend box “Node.js + Express + REST API”, and the database box “PostgreSQL :5432”.

Iterative Editing

After the initial diagram, the author added the sentence “Add a Redis cache layer between the backend and the database.” Codex regenerated the diagram with Redis inserted between the backend and PostgreSQL, and an arrow labeled “Cache”. This conversational editing is much faster than dragging elements in traditional diagram tools.

Export in Practice

Once satisfied, the author clicked the Copy button to paste the PNG directly into a Feishu document, then exported a PDF for future review. The resolution remained high and colors stayed true.

Author’s Assessment

The skill’s value lies in turning diagram creation from a design task into a description task. Users only need to articulate system components and connections; Claude handles layout and styling, saving time for reviews, documentation, and meetings.

Limitations include cramped layouts for very complex systems; the author mitigates this by adding spacing instructions in the description or splitting the architecture into multiple diagrams. The skill excels at software architecture, cloud infrastructure, and micro‑service topologies, but is unsuitable for physical hardware diagrams or generic flowcharts. For flowcharts, the author recommends the sister project process-flow-diagram-generator.

Overall, the workflow—from description to final diagram—takes about five minutes, compared to at least half an hour with Draw.io, freeing time for coding, design, or even leisure.

GitHub Repository

https://github.com/Cocoon-AI/architecture-diagram-generator