Stop Wrestling with Diagram Tools! Kroki Unifies 20+ Formats in One API

Stop Wrestling with Diagram Tools! Kroki Unifies 20+ Formats in One API

Here's a dirty secret that documentation teams don't want you to know: the average developer wastes 4+ hours per week switching between diagram tools. Mermaid for flowcharts. PlantUML for sequence diagrams. GraphViz for directed graphs. Excalidraw for sketches. Each tool with its own syntax, its own CLI, its own Docker^{↗ Bright Coding Blog} container, its own broken dependency chain.

Sound familiar? You've been there. You're documenting an architecture, and suddenly you need three different tools just to explain one system. Your CI pipeline looks like a Frankenstein monster of containerized diagram generators. Your team's "standard" is whatever tool the last person discovered on Hacker News.

What if I told you there's a single API that unifies 20+ diagram formats under one roof? No more context switching. No more dependency hell. No more explaining to your PM why the architecture diagram took three days instead of thirty minutes.

Enter Kroki — the open-source diagram generation API that top platform engineers are quietly adopting. Created by Yuzutech, this isn't just another diagram tool. It's the universal translator for textual diagram descriptions, and it might just end your diagram toolchain nightmare forever.

What is Kroki?

Kroki is a unified API service that generates diagrams from textual descriptions. Think of it as the "one API to rule them all" for diagram generation — a single endpoint that speaks every major diagram language, from legacy favorites like GraphViz to cutting-edge tools like D2.

The project was developed by Yuzutech, a company specializing in developer productivity tools, and has gained significant traction in the developer community for solving a genuinely painful problem: diagram tool fragmentation.

Why Kroki is Trending Now

The timing isn't accidental. Three forces are converging:

1. Docs-as-Code movement: Teams want diagrams version-controlled alongside their code, not locked in proprietary SaaS tools.
2. Markdown^{↗ Smart Converter}-native documentation: GitHub, GitLab, Notion, and Obsidian all support embedded diagrams — but each with different syntax requirements.
3. AI-generated documentation: LLMs excel at producing structured text. Kroki turns that text into visual diagrams automatically.

Kroki's architecture is deliberately modular. At its core sits a Java/Vert.x gateway server that routes requests to specialized companion containers. Need Mermaid? There's a container for that. BPMN? Another container. This design means you only run what you need, keeping resource usage lean while maintaining infinite extensibility.

The project's GitHub repository shows active development with CI/CD pipelines, a thriving Zulip community, and a growing ecosystem of integrations. It's not experimental abandonware — it's production-ready infrastructure that companies are deploying internally.

Key Features That Make Kroki Insane

Kroki isn't just a wrapper around existing tools. It's a fundamentally different approach to diagram generation with features that solve real engineering problems:

Universal Format Support

Kroki speaks 20+ diagram languages natively: BlockDiag (and its variants SeqDiag, ActDiag, NwDiag, PacketDiag, RackDiag), BPMN, Bytefield, C4 with PlantUML, D2, DBML, Diagrams.net (experimental), Ditaa, Erd, Excalidraw, GoAT, GraphViz, Mermaid, Nomnoml, Pikchr, PlantUML, SvgBob, Symbolator, UMLet, Vega, Vega-Lite, WaveDrom, and WireViz.

The killer insight: Your team can standardize on Kroki's API while letting different teams use their preferred diagram syntax. Backend team loves PlantUML? Frontend team swears by Mermaid? DevOps^{↗ Bright Coding Blog} needs GraphViz? Everyone wins.

Multiple Input Methods

Kroki offers three ways to submit diagrams, adapting to your workflow rather than forcing conformity:

• URL-encoded GET requests: Perfect for embedding in Markdown, wikis, or sharing quick links
• JSON POST payloads: Ideal for programmatic generation from applications and CI pipelines
• Plain text POST with headers: Cleanest option for API integrations and webhook handlers

Smart Encoding Algorithm

For GET requests, Kroki uses deflate compression + base64 encoding to minimize URL length. This isn't naive base64 — it's optimized for diagram text, which typically compresses extremely well due to repetitive structural patterns.

Containerized, Modular Architecture

Each diagram engine runs in its own container. The gateway server routes requests intelligently. This means:

• Independent scaling: Your Mermaid container can handle 1000 RPS while your BPMN container sleeps
• Isolated failures: A bug in the Excalidraw renderer won't crash your PlantUML diagrams
• Security boundaries: Untrusted diagram code runs in sandboxed environments

Self-Hostable with Docker

Kroki runs entirely on-premises. No SaaS lock-in, no data leaving your network, no pricing tiers based on "seats." For companies in regulated industries — healthcare, finance, government — this is non-negotiable.

Real-World Use Cases Where Kroki Dominates

1. Documentation Pipelines That Actually Work

Imagine committing a Markdown file with embedded diagram sources, and your CI pipeline automatically generates PNGs for PDF exports, SVGs for web viewing, and updates cached versions. Kroki makes this trivial. Teams at scale are replacing complex Makefiles and brittle Node.js scripts with a single Kroki endpoint.

2. Architecture Decision Records (ADRs) with Visuals

ADRs are text-heavy by design. But architecture without diagrams is like code without comments — technically complete, practically useless. Kroki lets you embed diagram sources directly in your ADR Markdown, rendering them on-the-fly in your documentation site.

3. Live API Documentation

OpenAPI specs describe endpoints beautifully, but system architecture? Not so much. By combining Kroki with tools like Swagger or Redoc, you can generate dynamic architecture diagrams that update automatically when your OpenAPI spec changes. The C4 model support is particularly powerful here.

4. ChatOps and Slack/Discord Bots

Need to quickly sketch a flowchart during an incident response? A Slack bot that POSTs to your internal Kroki instance can turn "User -> API -> Database -> Cache" into a shareable diagram in seconds. No context switching, no license checks, no "sign up for our free trial."

5. Educational Content and Technical Blogging^{↗ Bright Coding Blog}

Technical writers are using Kroki to maintain diagram sources in Git, rendering them through static site generators. When the architecture changes, update the text, commit, push — diagrams rebuild automatically. No more hunting through Figma files or Lucidchart versions.

Step-by-Step Installation & Setup Guide

Ready to escape diagram tool purgatory? Here's your complete deployment guide.

Prerequisites

• Docker Engine 20.10+ or Docker Desktop
• Docker Compose v2 (for multi-container setups)
• task command-line tool (installation guide)
• Maven 3.8+ (only if building from source)

Option 1: Quick Start with Docker (Recommended)

The fastest path to production:

# Pull and run the core Kroki gateway
docker run -d -p 8000:8000 yuzutech/kroki

That's it. You now have a diagram API running on localhost:8000.

But wait — this only includes built-in engines (PlantUML, GraphViz, etc.). For Mermaid, BPMN, Excalidraw, or diagrams.net, you need companion containers.

Option 2: Full-Featured Deployment with Docker Compose

Create a docker-compose.yml file:

services:
  core:
    image: yuzutech/kroki
    environment:
      # Tell the gateway where to find companion services
      - KROKI_MERMAID_HOST=mermaid
      - KROKI_BPMN_HOST=bpmn
      - KROKI_EXCALIDRAW_HOST=excalidraw
      # Optional: experimental diagrams.net support
      - KROKI_DIAGRAMSNET_HOST=diagramsnet
    ports:
      - "8000:8000"
  
  mermaid:
    image: yuzutech/kroki-mermaid
    expose:
      - "8002"  # Internal port, not exposed to host
  
  bpmn:
    image: yuzutech/kroki-bpmn
    expose:
      - "8003"
  
  excalidraw:
    image: yuzutech/kroki-excalidraw
    expose:
      - "8004"
  
  # Experimental: diagrams.net integration
  diagramsnet:
    image: yuzutech/kroki-diagramsnet
    expose:
      - "8005"

Deploy with:

docker-compose up -d

Verify all services are healthy:

docker-compose ps
# Should show all containers as "Up"

Option 3: Build from Source (Advanced)

For custom modifications or contributing to the project:

# Clone the repository
git clone https://github.com/yuzutech/kroki.git
cd kroki

# Build Java components with Maven
task mavenBuild

# Build all Docker images (requires sudo on most systems)
sudo task dockerBuildImages

Note: The task tool replaces traditional Makefiles with a more readable YAML-based format. If you haven't adopted it yet, this is a great excuse to explore Taskfile.dev.

Environment Configuration

Key environment variables for the gateway server:

REAL Code Examples from Kroki's Repository

Let's examine actual usage patterns from the Kroki documentation and README. These aren't hypothetical — they're production-tested patterns.

Example 1: GET Request with URL-Encoded Diagram

The simplest integration. Perfect for Markdown embeds, wikis, and quick sharing:

GET /plantuml/svg/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000

What's happening here?

• plantuml — the diagram language
• svg — desired output format (png, pdf, and others available)
• SyfFKj2rKt3CoKnELR1Io4ZDoSa70000 — deflate-compressed, base64-encoded PlantUML source

The encoded string represents: Bob -> Alice : hello

When to use this: Static documentation, cached renders, any scenario where URLs are convenient. The encoding keeps diagrams version-controllable as text while rendering as images.

Example 2: JSON POST for Programmatic Generation

The cleanest API for applications, CI pipelines, and dynamic generation:

{
  "diagram_source": "Bob -> Alice : hello",
  "diagram_type": "plantuml",
  "output_format": "svg"
}

Send this to POST / with Content-Type: application/json.

Key advantage: No encoding required. Your application can construct diagrams dynamically and POST them directly. This is how you'd build a Slack bot, a documentation generator, or an IDE plugin.

Production tip: Always specify "output_format": "svg" for web delivery — it's resolution-independent and typically smaller than PNG for diagram content.

Example 3: Plain Text POST with Headers

The HTTP-purist approach. Clean separation of concerns between content and metadata:

POST /plantuml
Accept: image/svg+xml
Content-Type: text/plain

Bob -> Alice : hello

Why this pattern matters: It follows REST conventions precisely. The Accept header negotiates format. The Content-Type declares payload type. The body contains pure diagram source with zero wrapping.

This integrates beautifully with HTTP client libraries, curl scripts, and tools that respect standard headers.

Example 4: Format in URL with Plain Text Body

When you can't control headers (looking at you, legacy systems and restricted environments):

POST /plantuml/svg
Content-Type: text/plain

Bob -> Alice : hello

The trade-off: Less HTTP-correct, more pragmatic. The output format moves from Accept header to URL path. This works in environments where header manipulation is restricted or where URL-based caching is preferred.

Example 5: JSON with Format in URL

Combining JSON convenience with URL-based format specification:

POST /plantuml/svg
Content-Type: application/json

{
  "diagram_source": "Bob -> Alice : hello"
}

Best of both worlds: Structured JSON for complex diagram sources (with newlines, special characters, unicode), but URL-based format for simpler client implementations.

Advanced Usage & Best Practices

Caching Strategy

Kroki's URL-encoded GET requests are naturally cacheable. The same diagram source always produces the same URL. Deploy Kroki behind Nginx or Varnish with aggressive caching rules. For internal deployments, consider:

location / {
    proxy_pass http://kroki-gateway:8000;
    proxy_cache_valid 200 1d;  # Cache successful renders for 1 day
    proxy_cache_use_stale error timeout;  # Serve stale on backend issues
}

Security Hardening

Diagram generation involves executing user-provided code. Kroki's container isolation helps, but defense in depth matters:

• Run companion containers with read-only filesystems where possible
• Use network policies to restrict container-to-container communication
• Enable resource limits (CPU/memory) to prevent DoS via complex diagrams
• Consider diagram complexity limits at your API gateway layer

High-Availability Deployment

For production workloads:

# docker-compose.prod.yml excerpt
services:
  core:
    image: yuzutech/kroki
    deploy:
      replicas: 3
      resources:
        limits:
          cpus: '2.0'
          memory: 2G
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

Format Selection Guide

Comparison with Alternatives

The verdict: If you need one diagram tool that handles everything, Kroki is unmatched. PlantUML Server is excellent for PlantUML-specific workflows. Mermaid.live is convenient for quick sketches. But only Kroki eliminates the "which tool for which diagram?" decision fatigue entirely.

FAQ: Developer Concerns Answered

Q: Does Kroki support real-time collaboration like Figma or Lucidchart? A: No — and that's intentional. Kroki is a rendering engine, not a design tool. It excels at automated, version-controlled diagram generation. Pair it with Git-based workflows for collaboration, not real-time editing.

Q: What's the performance impact of running multiple companion containers? A: Minimal for typical loads. Each container sleeps until needed. The gateway's Vert.x architecture handles 10,000+ concurrent requests efficiently. For massive scale, run multiple gateway instances behind a load balancer.

Q: Can I add custom diagram formats? A: Yes! Kroki's modular design makes this straightforward. Implement a container that accepts diagram source and returns image data, then register it with the gateway. The project documentation covers extension patterns.

Q: Is the diagrams.net integration production-ready? A: It's marked experimental in the documentation. Functional for evaluation, but exercise caution for critical workloads. The core engines (PlantUML, Mermaid, GraphViz) are battle-tested.

Q: How does Kroki handle diagram errors? A: Returns appropriate HTTP status codes with descriptive error messages. PlantUML syntax errors return 400 Bad Request with the compiler's error output. This makes debugging CI pipelines straightforward.

Q: Can I use Kroki with GitHub/GitLab Markdown? A: Absolutely. GitHub doesn't render arbitrary images from internal APIs, but GitLab's Markdown supports Kroki natively in recent versions. For GitHub, use Kroki in your documentation site's build pipeline (Hugo, Docusaurus, MkDocs all integrate well).

Q: What's the licensing? Can I use Kroki commercially? A: Kroki is open source with permissive licensing. Check the GitHub repository for current license details — typically MIT or Apache-style terms that permit commercial use.

Conclusion: Your Diagram Workflow Deserves Better

Let's be brutally honest: diagram tool fragmentation is a solved problem that most teams haven't solved yet. Every hour spent context-switching between Mermaid, PlantUML, GraphViz, and whatever else is an hour not spent building your actual product.

Kroki isn't just another tool to add to your stack. It's a tool eliminator — the unified API that lets your team standardize on one integration while preserving syntax flexibility. The containerized architecture means it scales from solo developer laptops to enterprise Kubernetes clusters. The multiple input methods adapt to your workflow, not the other way around.

I've evaluated dozens of diagram solutions over my career. Kroki is the first that made me think: "This is how it should have worked all along."

Your next step: Head to github.com/yuzutech/kroki. Star the repository. Deploy it with Docker Compose. Convert your most painful diagram workflow. Measure the time saved. Then come back and thank me — or better yet, contribute to the project.

The future of documentation is text-based, version-controlled, and automated. Kroki is the rendering engine that makes that future possible. Don't get left behind with broken toolchains and manual diagram exports.

Deploy Kroki this week. Your future self — and your documentation — will thank you.