Cocoon-AI/architecture-diagram-generator: AI-Powered Diagrams as Standalone HTML

Cocoon-AI/architecture-diagram-generator: AI-Powered Diagrams as Standalone HTML

Developers hate maintaining architecture diagrams. The tools are either too rigid—forcing you to drag boxes around for hours—or too abstract, producing outputs that look nothing like your actual system. Worse, most diagram formats require proprietary software or subscriptions, making them painful to share with teammates or embed in documentation.

Cocoon-AI/architecture-diagram-generator takes a different approach. It's a Claude AI skill that generates professional, dark-themed architecture diagrams as standalone HTML files. Describe your system in plain English, and Claude builds the diagram for you. No design tools. No subscription lock-in. Just a single file you open in any browser.

With 6,473 GitHub stars, 514 forks, and an MIT License, this open-source project has found traction among developers who want fast, shareable architecture visuals without the usual friction. The focus keyword architecture diagram generator captures exactly what it delivers: AI-assisted diagram creation that outputs self-contained, browser-ready files.

What is Cocoon-AI/architecture-diagram-generator?

Cocoon-AI/architecture-diagram-generator is a skill for Claude.ai that generates system architecture diagrams as standalone HTML/SVG files. It's maintained by Cocoon AI and falls into the category of AI-assisted developer tooling—specifically, prompt-to-diagram generators that leverage large language models for visual output.

The project's core insight is simple: most developers can describe their architecture accurately, but translating that description into a clean visual is tedious, error-prone, and often delegated until it becomes stale. By embedding diagram generation into a conversational AI workflow, the tool collapses the gap between system understanding and system documentation.

Technically, the skill works by combining Claude's natural language understanding with a structured HTML template (template.html) and skill instructions (SKILL.md). When invoked, Claude parses your architecture description, selects appropriate components from a semantic color palette, positions them logically, renders SVG connections, and packages everything into a single self-contained HTML file with embedded CSS.

The dark theme—slate-950 background with subtle grid pattern, JetBrains Mono typography, and semantic color coding—reflects a deliberate aesthetic choice that resonates with developers who spend hours in dark-mode IDEs. This isn't a generic diagram tool repurposed for tech; it's designed specifically for technical audiences who value consistency with their existing visual environment.

The project is actively maintained, with the last commit dated 2026-05-13. The HTML primary language is somewhat misleading—this is effectively a templating and prompt-engineering project where the HTML serves as the rendering target, not the application runtime.

Key Features

Conversational diagram creation. The entire workflow happens through natural language. You describe components and connections; Claude handles positioning, styling, and rendering. This eliminates the manual layout drag-and-drop that consumes most of the time in traditional diagram tools.

Standalone HTML output. Every diagram is a single .html file with embedded CSS and inline SVG. No dependencies, no build step, no server required. Open it in Chrome, Firefox, Safari, or Edge. Email it to a colleague. Host it on S3 or GitHub Pages. The portability is genuine, not theoretical.

Built-in export options. The generated HTML includes toolbar buttons for Copy (high-resolution PNG to clipboard), PNG download, and PDF download. This covers the three most common sharing contexts: Slack/Teams messages, slide decks, and formal documentation. No external tools needed.

Semantic color coding. Components are automatically assigned colors based on type:

This consistency means diagrams remain readable across different systems and teams without ad-hoc color decisions.

Smart visual layering. Arrows render behind component boxes through deliberate z-ordering, with opaque backgrounds masking line intersections. The SVG viewBox (typically 1000-1100px wide) scales responsively across screen sizes.

Iterative refinement. Because the workflow is conversational, you can ask Claude to add components, change layouts, update labels, or fix connection logic without starting over. The feedback loop is measured in seconds, not hours.

Use Cases

Documenting existing systems. Teams inheriting legacy codebases often lack accurate architecture diagrams. Feed the tool a codebase analysis from Cursor, Claude Code, or Windsurf, and generate a visual reference that stays current as the system evolves. The [INTERNAL_LINK: code analysis tools] category has grown precisely because this gap is so common.

Design reviews and proposals. Before committing to infrastructure changes, describe the proposed architecture and generate a shareable diagram for stakeholder review. The dark theme and professional typography present well in technical meetings without additional polish.

Onboarding documentation. New engineers learn faster with visual system maps. A single HTML file in the repo's docs/ directory, generated from the current architecture description, beats outdated wiki pages that drift from implementation reality.

Incident response and runbooks. During outages, clear architecture diagrams help responders trace failure paths. The quick generation means you can produce focused diagrams showing only affected components and their dependencies, rather than wading through comprehensive but irrelevant system maps.

Microservices communication patterns. The example prompts explicitly cover multi-service architectures with API gateways, polyglot backends, event streaming, and Kubernetes orchestration. These complex topologies benefit most from automated layout—manual tools struggle with the combinatorial explosion of connections.

Installation & Setup

The skill supports three installation paths. Choose based on your Claude access pattern.

Claude.ai Web Interface (Recommended)

1. Download architecture-diagram.zip from the repository
2. Navigate to claude.ai → Customize → Skills
3. Click the + button → + Create skill → Upload a skill
4. Select the zip file and toggle the skill on

Prerequisite: Code Execution must be enabled in Settings → Capabilities (Free/Pro/Max) or by your organization admin (Team/Enterprise).

Claude.ai Projects (Alternative)

Upload architecture-diagram.zip directly to your Project Knowledge. This scopes the skill to a specific project without global installation.

Claude Code CLI

For terminal-first workflows:

# Global skills (available across all Claude Code sessions)
unzip architecture-diagram.zip -d ~/.claude/skills/

# Or project-local (checked into version control)
unzip architecture-diagram.zip -d ./.claude/skills/

The extracted structure must preserve:

architecture-diagram/
├── SKILL.md              # Skill instructions for Claude
└── resources/
    └── template.html     # Base HTML template with embedded styles

Both files must remain accessible to Claude for diagram generation to function. The SKILL.md contains the prompt engineering that guides Claude's component selection, layout decisions, and output formatting. The template.html provides the CSS framework, SVG scaffolding, and export button handlers.

Real Code Examples

The README provides three concrete prompt patterns that demonstrate the tool's input format. These are not abstract documentation—they're copy-paste ready starting points.

Example 1: Web Application Stack

Create an architecture diagram for a web application with:
- React↗ Bright Coding Blog frontend
- Node.js/Express API
- PostgreSQL↗ Bright Coding Blog database
- Redis cache
- JWT authentication

This prompt shows the minimal viable description: list technologies and their roles. Claude infers the connections (frontend → API → database/cache, JWT spanning the security layer) and assigns semantic colors automatically. The output includes protocol labels and port annotations where relevant.

Example 2: AWS Serverless Architecture

Create an architecture diagram showing:
- CloudFront CDN
- API Gateway
- Lambda functions (Node.js)
- DynamoDB
- S3 for static assets
- Cognito for auth

This demonstrates cloud-native topology with managed services. The amber color coding for AWS components triggers automatically, and the diagram likely shows regional boundaries or service groupings that help distinguish control flow from data flow.

Example 3: Microservices with Polyglot Backends

Create an architecture diagram for a microservices system with:
- React web app and mobile clients
- Kong API Gateway
- User Service (Go), Order Service (Java), Product Service (Python↗ Bright Coding Blog)
- PostgreSQL, MongoDB, and Elasticsearch databases
- Kafka for event streaming
- Kubernetes orchestration

This is the stress test: multiple clients, polyglot services, heterogeneous databases, event streaming, and container orchestration. The automated layout becomes essential here—manual tools require significant time to position this many components without overlapping connections.

The README notes that after initial generation, you iterate by chat: "Please update XYZ" triggers real-time diagram updates. This conversational refinement is the core workflow advantage over static diagram tools.

Advanced Usage & Best Practices

Source your descriptions accurately. The tool is only as good as its input. For existing systems, use AI code analysis (Cursor, Claude Code, Windsurf, ChatGPT) to generate the component list, then verify against actual infrastructure. Hallucinated components in the description become hallucinated components in the diagram.

Version control your prompts. Save the natural language descriptions alongside generated HTML files. When the architecture changes, edit the prompt and regenerate rather than manually patching the SVG. This treats diagrams as derived artifacts from canonical text descriptions.

Leverage semantic colors for team conventions. The fixed color palette (cyan/emerald/violet/amber/rose/slate) can anchor team documentation standards. Agree that "violet always means database" and diagrams become instantly parseable across projects.

Export strategically. Copy-to-clipboard PNG works best for Slack/Teams quick shares. Downloaded PNG suits slide decks. PDF preserves the dark theme for formal documentation where print fidelity matters.

Consider the sister skill for temporal flows. The README references process-flow-diagram-generator for step-by-step workflows, approval chains, and automation pipelines. Same design language, different visual grammar—use both for comprehensive system documentation.

Comparison with Alternatives

Mermaid and PlantUML are the closest text-to-diagram alternatives, but both require learning a domain-specific language. The Cocoon-AI skill accepts plain English, lowering the barrier for team members who diagram infrequently. However, Mermaid and PlantUML offer finer control for users who need precise layout enforcement—Cocoon-AI delegates positioning to Claude's judgment.

Draw.io provides maximum manual control but no AI assistance. It's preferable for one-off polished diagrams where time investment is justified. Cocoon-AI wins for rapid iteration and maintaining diagram currency.

Lucidchart and similar SaaS tools lock diagrams behind subscriptions and lack programmatic generation. The Cocoon-AI skill's MIT-licensed, file-based output avoids vendor lock-in entirely.

FAQ

Is this free to use? Yes. MIT License. The Claude.ai skill works on Free, Pro, Max, Team, and Enterprise plans, though Code Execution must be enabled.

Do I need design skills? No. The entire workflow is conversational. You describe; Claude generates.

Can I use this without Claude.ai? Not practically. The skill depends on Claude's natural language understanding and code execution capabilities. The template and instructions are open, but the generation logic is Claude-hosted.

What browsers are supported? Any modern browser. The output is standard HTML5 with embedded SVG—no exotic dependencies.

How do I update a diagram after generation? Continue the conversation. Ask Claude to add components, change connections, or restyle elements. Regenerate the HTML file.

Can I customize the color palette? The semantic colors are fixed in the current template. Fork the repository and modify resources/template.html if you need different branding.

Is there a CLI or API? No direct CLI. The Claude Code installation path provides terminal-adjacent access, but generation still routes through Claude.

Conclusion

Cocoon-AI/architecture-diagram-generator solves a specific, well-defined problem: transforming architecture descriptions into shareable, professional diagrams without design tool overhead. It's best suited for teams already using Claude.ai who need rapid, iterative diagram creation that stays current with system changes.

The 6,473 stars and 514 forks suggest genuine developer adoption, not just repository inflation. The MIT license and standalone HTML output align with open-source values of portability and vendor independence. The dark theme and semantic color system show attention to developer experience details that generic diagram tools overlook.

It's not a replacement for precise manual layout when pixel-perfect control matters. It is a compelling alternative when speed, iteration, and maintainability dominate. If your architecture documentation is perpetually out of date, or if you've avoided creating it because the tools feel worse than the problem, this skill merits evaluation.

Explore the repository, try the installation paths, and generate your first diagram from a plain English description: https://github.com/Cocoon-AI/architecture-diagram-generator