Skip to content
Software Architecture Guide

Kroki

Explanation

Section titled “Explanation”

Kroki turns diagram descriptions written as text into images. Many tools exist for this, and each has its own setup. Kroki puts a single API in front of them. You learn one way of working and use it for every supported library.

Why one API helps

The underlying diagram libraries are written in many languages, such as Haskell, Python, JavaScript, Go, PHP, and Java. Kroki hides this mix behind the single API. You do not need to install each library and its requirements yourself.

Two ways to run it

Kroki is available as a free public service. It is also available as a self-managed instance. With the self-managed option, you download and install Kroki on your own infrastructure or in a cloud environment.

Calling the API

There are two request styles:

  • GET: The diagram source goes into the URL. You must compress it with deflate and then encode it with base64.
  • POST with plain text: You send the diagram source as the request body. You choose the output format with the Accept header.

Who builds it

Kroki is open source under the MIT license. Yuzu tech builds and maintains the free service, with support from Exoscale.

Keeping diagrams as text fits the ideas in Diagrams as Code and Documentation as Code.

Example

Section titled “Example”

A team keeps its architecture diagrams as text files in the same repository as its documents. The diagrams use different libraries, and the team installs none of them. A script sends each text file to Kroki and receives an image back. For a quick test, the team uses the free public service. Later, they might run their own instance on their own servers.

Trade-offs

Section titled “Trade-offs”

The facts available here do not cover privacy, security, or performance differences between the public service and a self-managed instance. Check those points yourself before sending sensitive diagrams to any external service. The self-managed option means you install and run Kroki on your own infrastructure or in the cloud. The free public service avoids that work.

One API in front of many diagram libraries

Diagram source 
flowchart LR
  A[Diagram as text] --> B[Kroki API]
  B --> C[Library 1]
  B --> D[Library 2]
  B --> E[Library 3]
  B --> F[Image output]

Checks

Section titled “Checks”
  • The documentation states whether diagrams are rendered with the free public Kroki service or a self-managed instance.
  • If GET requests are used, the diagram source is deflate-compressed and base64-encoded in the URL.
  • If POST with plain text is used, the output format is chosen with the Accept header.
Section titled “Related”

Sources

Section titled “Sources”