C4X - C4 Model Diagrams for VS Code

Status (2025-12-22): ✅ v1.2.11 STABLE - AI Model Upgrade + Visual Diagram Generation (Preview)

License

Make C4 architectural diagrams as easy as getting AI to do this for you... - Jaroslav

Fast, offline, Mermaid-inspired C4 diagrams with real-time preview and support for multiple DSL formats - now powered by Gemini AI.

✨ Features

⚡ Instant preview - Sub-50ms rendering for 30-node diagrams
🔍 Real-time Validation - Syntax highlighting and error reporting as you type
📝 Markdown Integration - Render ```c4x blocks directly in your README files
🎨 5 built-in themes - Classic, Modern, Muted, High Contrast, Auto
📝 Simple DSL - Mermaid-inspired C4X syntax
🚀- Zero Dependencies: No Java, no Graphviz, no Docker required. Everything is bundled in the extension.

🛠️ Improvements)

🔒 Secure - CSP-compliant, no external CDN dependencies
📤 Export - Save as SVG/PNG or Print to PDF
☁️ Cloud Icons - AWS, Azure, GCP & Tech Stack icons (via PlantUML syntax)
🧩 Icon IntelliSense - Autocomplete for over 1500+ AWS, Azure, and GCP icons directly in the editor
🔄 PlantUML Support - Use standard PlantUML C4 syntax directly
🧠 Intelligent Architecture (Gemini AI) - Your pair programmer for diagrams.
- Generate from Code: Analyzes Workspace files (.ts, .java, .py) to create accurate C4 models.
- Sketch-to-Code: Select any text (notes, ASCII art, user stories) and turn it into a diagram.
- Visual Generation (Preview): Generate PNG images directly using gemini-3-pro-image-preview. 🆕
- Smart Layouts: Automatically optimizes for screen space (Horizontal vs Vertical).
- Enterprise Ready: Supports Vertex AI keys for zero-data retention.
- 📘 Gemini AI Guide | 📘 Visual Diagram Guide

🎥 Watch 30s Demo - Build Diagrams with Gemini AI

⚡ Lightning fast activation - 0.15ms startup (99.9% faster than 200ms target)

🎨 Rich Icon Integration (v1.1.9)

Visualize real-world architectures with AWS, Azure, GCP, and React icons using the simple $sprite syntax.

C4X Icons Example

📘 View Full Icon Guide & Examples

🖼️ Visual Diagram Generation (v1.2.1 Preview)

Generate presentation-ready PNG diagrams directly from text using gemini-3-pro-image-preview - no DSL syntax required!

Generate from Selection: Highlight any text (ASCII art, notes, requirements) and run C4X: Diagram from Selection.
Smart Layouts: Automatically switches between Horizontal (for flows) and Vertical (for hierarchies).
Styles: Enforces official C4 colors and shapes.

PNG Flow diagram from Selection

Example: PNG Flow diagram from Selection - generated from another ASCII graphic

📘 Visual Diagram Guide

🚀 Quick Start

Installation

From VS Code Marketplace (Recommended):

Open VS Code
Press Ctrl+Shift+X (or Cmd+Shift+X on Mac)
Search for "C4X"
Click "Install"

From Command Line:

code --install-extension jpantsjoha.c4x

Usage

Create a C4X file: banking-system.c4x

Write your diagram:

%%{ c4: system-context }%%
graph TB

Customer[Customer<br/>Person]
Banking[Banking System<br/>Software System]
Email[Email System<br/>Software System<br/>External]

Customer -->|Uses| Banking
Banking -->|Sends notifications| Email

Open preview: Press Ctrl+K V (or Cmd+K V on Mac)
See instant results: Your diagram renders in < 50ms!

That's it! No Java, no servers, no configuration needed.

Markdown Integration

You can embed C4X diagrams directly in your markdown files (e.g., README.md, ARCHITECTURE.md).

# My Architecture

Here is the system context:

```c4x
%%{ c4: system-context }%%
graph TB
    User[User<br/>Person]
    System[My System<br/>Software System]
    User -->|Uses| System
```

The extension will automatically render this code block as a visual SVG diagram in the VS Code Markdown Preview.

📚 Examples & Use Cases

C4X makes it easy to visualize complex architectures, from traditional web apps to advanced AI agent systems.

Featured Example: Multi-Agent Marketing System (C1 - System Context)

This diagram visualizes the high-level interactions for an AI-powered marketing system, featuring human roles, the multi-agent platform, and external AI services.

Multi-Agent System Context

C2: Multi-Agent Orchestrator (Container Diagram)

A container-level view of the Multi-Agent Marketing System, detailing the main building blocks within the Multi-Agent System.

Multi-Agent Orchestrator

📚 Examples & References

For comprehensive galleries and guides, explore our documentation:

Example Gallery: A rich collection of C4 diagrams (Banking, Microservices, AI Agents).
Cloud Icons & AI: Using $sprite and Gemini for cloud architectures.
Visual Diagrams: Generate PNG diagrams with Gemini Image model. 🆕
Layout Guide: Controlling diagram direction (TB, LR).
Ordering Guide: Controlling node order.
PlantUML Guide: Using standard PlantUML syntax.
Syntax Guide: Full DSL reference.

🧠 Gemini AI Architect (Setup)

📘 Full Guide: See docs/GEMINI_GUIDE.md for advanced usage, prompt engineering tips, and troubleshooting.

1. Get an API Key

For Personal Projects: Get a free key from Google AI Studio. (Note: Data may be used for training).
For Enterprise/Work: Create a key in your Google Cloud Console (Vertex AI). (Note: Compliant with GCP data privacy terms).

2. Authentication

Option A (Interactive): Right-click any markdown file -> C4X: Generate Diagram. If no key is found, paste it when prompted.
Option B (Settings): Set "c4x.ai.apiKey": "YOUR_KEY" in VS Code settings.

3. AI Model Configuration (v1.2.0)

C4X uses a tiered model strategy for optimal performance and reliability:

Priority	Model	Use Case
Primary	`gemini-3-flash-preview`	Default - Pro-grade reasoning at Flash speed (3x faster)
Fallback	`gemini-3-pro-preview`	Auto-fallback if primary fails
Legacy	`gemini-2.5-pro`	Available for compatibility

Self-Validation: All AI-generated diagrams are automatically validated using the C4X parser. If syntax errors are detected, the model self-corrects and retries before returning results.

📖 C4X-DSL Syntax Guide

Elements

ElementID[Label<br/>Type<br/>Tags]

Supported Types:

Person - Users of the system
Software System - High-level software systems
Container - Applications, services, databases
Component - Code-level components

Example:

Admin[Administrator<br/>Person]
API[Payment API<br/>Software System]
DB[User Database<br/>Container<br/>Internal]

Elements with Icons (Function Syntax)

To use the 1500+ built-in icons, use the function-call syntax. IntelliSense will autocomplete icon names when you type $sprite=".

Standard: $sprite="aws-s3-bucket"
Namespace (New): $sprite="c4xicons.aws.s3-bucket" (Auto-resolves to correct icon)

Container(WebApp, "Web App", "React", $sprite="react")
ContainerDb(DB, "Database", "PostgreSQL", $sprite="c4xicons.aws.rds")
Container(S3, "Storage", "AWS S3", $sprite="c4xicons.aws.s3-bucket")

Relationships

%% Uses (Dashed)
FromID -->|Label| ToID
%% Async (Dashed)
FromID -.->|Label| ToID
%% Sync / Strong (Solid)
FromID ==>|Label| ToID

Example:

User[User<br/>Person]
Dashboard[Reporting Dashboard<br/>Container]
API[Reporting API<br/>Container]
Database[Reporting Database<br/>Container]

User -->|Views reports| Dashboard
Dashboard -.->|Fetches data| API
API ==>|Queries| Database

Boundaries / Subgraphs

Group elements into systems or containers using subgraphs.

subgraph BoundaryId {
    Element1[Label<br/>Type]
    Element2[Label<br/>Type]
}

Example:

graph TB
    User[User<br/>Person]

    subgraph BankingSystem {
        WebApp[Web App<br/>Container]
        Database[DB<br/>Container]
    }

    User -->|Uses| WebApp
    WebApp ==>|Reads/Writes| Database

View Types

%% C1 - System Context
%%{ c4: system-context }%%
%% C2 - Container (coming soon)
%%{ c4: container }%%
%% C3 - Component (coming soon)
%%{ c4: component }%%

🎨 Themes

Choose from 5 built-in themes to match your documentation style:

Theme	Description	Use Case
Classic	Official C4 Model colors (Simon Brown spec)	Standard C4 documentation
Modern	Vibrant colors with rounded corners	Presentations, modern docs
Muted	Grayscale minimalist	Professional reports, B&W printing
High Contrast	WCAG AAA compliant (7:1 ratio)	Accessibility, readability
Auto	Adapts to VS Code light/dark theme	Match your editor theme

Change Theme:

Command Palette: C4X: Change Theme
Settings: "c4x.theme": "modern"

📤 Export Diagrams

Export your diagrams to SVG or PNG with theme preservation:

Export Commands:

C4X: Export SVG - Vector format for editing (Figma, Sketch, Adobe Illustrator)
C4X: Export PNG - Raster format for documentation and presentations
C4X: Copy SVG to Clipboard - Quick paste into other applications

Features:

✅ Theme preservation (exported diagrams match your selected theme)
✅ High-quality rendering (no pixelation in SVG)
✅ Design tool compatibility (Figma, Sketch tested)
✅ Small file sizes (~20-50KB for typical diagrams)

📋 Commands

Command	Shortcut	Description
`C4X: Open Preview`	`Ctrl+K V` (Mac: `Cmd+K V`)	Open live preview panel
`C4X: Export SVG`	-	Export diagram to SVG file
`C4X: Export PNG`	-	Export diagram to PNG file
`C4X: Copy SVG to Clipboard`	-	Copy SVG to clipboard
`C4X: Change Theme`	-	Switch between 5 built-in themes

⚡ Performance

Exceeds all targets by 72-99%:

Metric	Target	Achieved	Status
Activation Time	< 200ms	0.15ms	✅ 99.9% faster
Bundle Size	< 1MB	386KB	✅ 63% under target
C4X Parse	< 50ms	10ms avg	✅ 80% faster
Preview Render	< 250ms	55ms avg	✅ 78% faster
Full Pipeline	< 300ms	55ms avg	✅ 82% faster

Tested with: 30-node diagrams (typical real-world size)

🛠️ Configuration

Settings

Configure C4X in your VS Code settings (Ctrl+, or Cmd+,):

{
  // Choose your preferred theme
  "c4x.theme": "classic",
  // Options: "classic", "modern", "muted", "high-contrast", "auto"
}

File Associations

C4X automatically recognizes these file extensions:

.c4x - C4X-DSL (Mermaid-inspired syntax)

🏗️ Project Status

Phase 1 (M0 - Scaffolding): ✅ Complete (v0.1.0) Phase 2 (M1 - C4X-DSL MVP): ✅ Complete (v0.2.0) Phase 3 (M2 - Themes & Export): ✅ Complete (v0.3.0) Phase 4 (M3 - Structurizr DSL): ⏳ Deferred to v1.2 Phase 5 (M4 - PlantUML C4): ⏳ Deferred to v1.2

See docs/STATUS.md for detailed roadmap.

🗺️ Roadmap

v1.1.8 (December 2025) ✅ Gemini AI Release

🧠 Gemini AI Integration - Text-to-Diagram (Shipped)
- Generate from Code: Workspace scanning (C1/C2/C3 support).
- Sketch-to-Code: Create diagrams from text selections.
- Smart Layouts: Auto-detection of Flow vs Hierarchy.
📐 Advanced Layout Control - Manual positioning overrides.

v1.2.1 (December 2025) ✅ AI Model Upgrade + Visual Generation

🧠 AI Model Upgrade - Upgraded to gemini-3-flash-preview (3x faster)
🎨 Visual Diagram Generation - PNG diagrams via gemini-3-pro-image-preview. 🆕
🔄 Self-Validation - Auto-correction for AI-generated diagrams.
📘 Visual Diagram Guide

v1.3.0 (Q1 2026) 🏗️ Advanced Integrations

⏳ Structurizr DSL Support - Native parsing of .dsl files.
🖼️ Custom Local Icons - Support for $sprite="./assets/logo.png".
🔮 Deployment Diagrams - Visualize infrastructure (Nodes, Pods, Regions).
📦 Workspace Diagnostics - Dedicated panel for architecture health.

v2.0.0 (Q2 2026) 🤖 Agentic Architecture

🧠 Agent Syntax - First-class support for AI_Agent, Memory, Tool.
🛡️ Architecture Analysis - Automated detection of bottlenecks and security risks.
✨ Generative Refactoring - "Suggest improvements" for your architecture.

📚 Documentation

Contributing - Contribution guidelines

🤝 Contributing

Contributions welcome! We'd love your help to make C4X even better.

Ways to contribute:

🐛 Report bugs or suggest features via GitHub Issues
📝 Improve documentation or examples
🎨 Design new themes or icons
🧪 Write tests for edge cases
⚡ Performance optimizations
⚡ Performance optimizations

✅ Validation

To ensure that documentation diagrams are syntactically and semantically correct, use the provided validation script. This checks for parser errors, invalid relationships, and unsupported element types.

# Verify all markdown files in the repository
./scripts/validate_c4x.sh

See CONTRIBUTING.md for detailed guidelines.

👤 More from the Author

Check out my other VS Code extension:

Pine Script™ (v5) - Syntax highlighting, snippets, and linting for TradingView's Pine Script.
- GitHub Repository

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

C4 Model by Simon Brown - The architectural modeling standard
Mermaid.js - Inspiration for C4X-DSL syntax
Dagre.js - Hierarchical graph layout engine

C4X - C4 Model Diagrams

Jaroslav Pantsjoha

C4X - C4 Model Diagrams for VS Code

✨ Features

🛠️ Improvements)

🎥 Watch 30s Demo - Build Diagrams with Gemini AI

🎨 Rich Icon Integration (v1.1.9)

🖼️ Visual Diagram Generation (v1.2.1 Preview)

🚀 Quick Start

Installation

Usage

Markdown Integration

📚 Examples & Use Cases

Featured Example: Multi-Agent Marketing System (C1 - System Context)

C2: Multi-Agent Orchestrator (Container Diagram)

📚 Examples & References

🧠 Gemini AI Architect (Setup)

📖 C4X-DSL Syntax Guide

Elements

Elements with Icons (Function Syntax)

Relationships

Boundaries / Subgraphs

View Types

🎨 Themes

📤 Export Diagrams

📋 Commands

⚡ Performance

🛠️ Configuration

Settings

File Associations

🏗️ Project Status

🗺️ Roadmap

v1.1.8 (December 2025) ✅ Gemini AI Release

v1.2.1 (December 2025) ✅ AI Model Upgrade + Visual Generation

v1.3.0 (Q1 2026) 🏗️ Advanced Integrations

v2.0.0 (Q2 2026) 🤖 Agentic Architecture

📚 Documentation

🤝 Contributing

✅ Validation

👤 More from the Author

📄 License

🙏 Acknowledgments