Why 'Diagrams as Code'?

Jimmy Zhou — Sat, 01 Aug 2026 11:39:39 +0000

If you’ve spent any time leading software projects or designing systems, you’ve probably experienced the Architecture Diagram Curse:

You spend two hours carefully arranging boxes, arrows, and colors on a visual canvas.
It looks beautiful. You put it in the documentation.
Two weeks later, the system architecture changes.
Nobody updates the diagram, and it becomes a lie. 😅

For a long time, standard drag-and-drop tools were the default. But as workflows become faster and AI gets integrated into daily coding, Diagrams as Code (DaC) is shifting from a niche preference to a genuine best practice.

Here’s why text-driven architecture is winning—and why it might be time to rethink your documentation stack.

The Problem with Static Visual Canvases

Visual canvases are great for quick brainstorming, but they fall short in modern, fast-moving development environments:

High Maintenance Friction: Moving one component often means re-aligning 10 connecting lines manually.
Incompatible with AI: Large Language Models (LLMs) think in text and code, not visual pixel layouts. You can't ask ChatGPT or Gemini to "drag a box to the left," but you can ask them to refactor a block of text.
Context Switching: Jumping out of your IDE to tweak a standalone graphics file breaks your flow state.

Enter Open Standards: PlantUML & Mermaid

The real power of Diagram as Code comes from open text standards. Tools like PlantUML and Mermaid let you treat system documentation the same way you treat source code: as plain text.

Instead of wrestling with a layout engine, you write something like this:

sequenceDiagram
    autonumber
    Client->>API Gateway: POST /checkout
    API Gateway->>Order Service: Process Order
    Order Service->>Payment API: Charge Card
    Payment API-->>Order Service: Success (200 OK)
    Order Service-->>Client: Order Confirmed

And just like that, you get a Sequence Diagram rendered instantly:

Attribution: Created with Visual Paradigm VPasCode

Why This Shift Is Huge:

AI-Ready: You can prompt an LLM to generate an entire sequence diagram or refactor a class structure in seconds.
Refactoring at Scale: Need to rename OrderService to FulfillmentService across 12 diagrams? A simple find-and-replace takes 5 seconds.
Portability: You aren't locked into a single app's proprietary .canvas or binary format.

Closing the Gap: Code Speed + Visual Flexibility

Of course, DaC isn't perfect out of the box. Pure text-to-diagram setups can sometimes feel rigid when you want to tweak visual themes, handle complex multi-syntax projects, or quickly export clean visuals for a stakeholder presentation.

This is where the ecosystem is evolving. Modern platforms are starting to blur the line between code and visual engines. For instance, unified tools - like Visual Paradigm's recent VPasCode engine - are emerging to recognize open standards like PlantUML, Mermaid, and Graphviz while giving you live web rendering, flexible styling, and easy sharing URLs under one roof.

Being able to prompt code with AI, render it instantly in a unified environment, and still touch it up visually gives you the best of both worlds.

Gemini AI + VPasCode: A Review of Visual Paradigm’s Diagram-as-Code Tool

Jimmy Zhou — Sat, 01 Aug 2026 10:53:45 +0000

Visual diagramming tools have always had a place in modern development. Being able to drag, drop, and visually structure complex architecture is indispensable when designing systems.

However, with the rise of AI tools like Gemini, the modern developer workflow is evolving fast. Today, we don't always want to start diagrams from scratch - we want to generate initial models using natural language, and fine-tune as text.

Visual Paradigm has been a major player in visual modeling software for decades, and they've recently released a tool called VPasCode - a unified diagram-as-code platform designed to blend modern AI generation with flexible modeling power. I decided to give it a spin to see how it fits into an AI-assisted workflow.

Why Diagram-as-Code Fits the Modern AI Workflow

While traditional visual canvas editing is still great for quick manual adjustments, Diagram-as-Code shines in the era of AI for three main reasons:

Natural LLM Output: Large Language Models (LLMs) output text and code natively. Generating text-based markup like PlantUML or Mermaid takes an LLM just seconds.
Speed & Efficiency: Writing or prompting markup lets you build massive class or sequence diagrams without placing every shape manually.
Multi-Engine Flexibility: You aren't tied to a single dialect.

VPasCode acts as a unified diagram-as-code engine supporting PlantUML, Mermaid, Graphviz, ECharts, Markmap, SQL, and many programming languages under one roof.

My Workflow: From Gemini Prompt to Polished Diagram

Here is a practical look at how I use Gemini AI + VPasCode to build robust class diagrams in a fraction of the time.

Step 1: Prompting Gemini for the Initial Model

Instead of laying out boxes manually, I give Gemini a high-level architectural prompt:

"Generate a PlantUML class diagram for an e-commerce platform covering Orders, Customers, Payments, and Inventory with proper object relationships."

Gemini outputs structured markup in seconds:

@startuml
class Customer {
  +String id
  +String name
  +placeOrder()
}

class Order {
  +String orderId
  +Date createdDate
  +calculateTotal()
}

class Payment {
  +String paymentId
  +Boolean process()
}

Customer "1" -- "0..*" Order
Order "1" -- "1" Payment
@enduml

Step 2: Instant Rendering & Touch-Ups in VPasCode

I copy Gemini's output directly into VPasCode. The class diagram renders instantly.

From there, I get complete editing freedom:

Text-First Adjustments: I can quickly edit classes, attributes, operations, and relationships as code and see the visual updates in real time.
Custom Themes & Export: Switching visual themes takes a click, and once the design is ready, I can export it as a clean PNG to drop straight into a design document or report.
Seamless URL Sharing: This is one of my favorite features—diagrams can be shared directly via a dynamic URL. As you edit, the URL updates live to reflect your latest state. You can simply copy and send that link to teammates for instant sharing without forcing anyone to sign up or download files.

The Best of Both Worlds

You don't have to choose between visual design and text-based speed anymore. By combining AI's generative power with VPasCode's multi-syntax support (PlantUML, Mermaid, Graphviz), software design and documentation becomes faster, smarter, and far more flexible.

👉 Want to try it yourself? Check out VPasCode and test your AI-generated diagrams today.

Have you tried using AI to bootstrap your architectural diagrams? What markup language do you find yourself using most? Let’s chat in the comments!

DEV Community: Jimmy Zhou