Today's Deep-Dive: Kroki

Have you ever found yourself, you know, needing to draw a diagram, maybe for a

system or a process,

or even just a simple flowchart, and you think about opening up some complicated

software and you

just, oh, sigh, all that dragging and dropping, finding the right shapes that can

be a real drag?

Well, today we're doing a deep dive into something that might just change all that

for you.

Kroki. It's this really interesting technology aiming to make visual communication

way easier.

But before we unpack exactly how it works and why it's getting attention,

a quick word from our supporter. This deep dive is brought to you by Safe Server.

Safe Server handles

hosting for software like Kroki and can really help with your digital

transformation. You can

find out more at www.safeserver.de. Okay, so our mission today is to demystify Kroki.

We've looked

at the info from their GitHub repository, their official website, and we're going

to break it down

so anyone really technical background or not can get what it is, how it works, and

why it might be

a game changer. Yeah, what's really fascinating, I think, is how Kroki bridges that

gap. You know,

between just plain text and these quite complex professional-looking visuals, it

makes diagramming

accessible in a way traditional tools often don't. Right, so let's unpack that. At

its core, Kroki

creates diagrams from text descriptions. You literally write some simple text,

maybe a few

lines that look a bit like code, and boom, out pops a diagram. Which sounds almost

too simple,

doesn't it? But why is that actually a big deal? Especially if you're maybe just

starting out with

diagrams. Most tools, you know, they have a specific interface you need to learn.

Drag and drop,

menus, sometimes different software for different types of diagrams. Kroki just

cuts through that.

Describe it in text, it draws it. And here's where it gets really powerful, I think.

Kroki is a

unified API. That means it acts like one single doorway to a whole bunch of

different diagram

tools and libraries. A massive array, actually. Yeah, we're talking things like

PlantUML,

which is great for sequence diagrams. BPMN for business processes. C4 for software

architecture.

Graph Fizz. Mermaid, which is super popular. Excalibur for more sketch-like

diagrams. Dita,

Erd. The list is huge. It really is. And connecting that to the bigger picture,

it just massively reduces friction. Think about developers, analysts, project

managers,

anyone needing to visualize something. Suddenly, you don't need to install five

different tools,

learn five interfaces, worry about compatibility. Exactly. Kroki aims to be ready

to use. No complex

setup for the public service. It's simple because of that unified API. And it's

free and open-source,

which is huge. It's on GitHub. The goal is a free service. Plus, it's designed to

be fast.

Modern architecture. Pretty efficient. So what does that mean for you listening? It

means you can whip

up quite sophisticated diagrams without needing graphic design skills or spending

ages learning

specific software. It's kind of a shortcut. It is. It's a shortcut to clear

communication.

I remember wrestling with alignment tools and drawing software for aging. Just

typing it sounds

so much better. Definitely. It forces you to think clearly, too, maybe. Like, you

have to describe

the relationships logically in text first. That's a really good point, actually. It's

not just about

the output. Writing it down forces clarity, unlike just, you know, randomly moving

boxes around on a

canvas. Okay, so we get what it is and why it's pretty significant. But how does

the magic happen?

How does Kroki turn your text into, say, an SVG or a PNG image? Right, the under-the-hood

stuff.

It mainly uses an HTTP API. An API is just, what, a standardized way for computer

programs to talk

to each other, send information back and forth. Okay. And Kroki handles both Git-T

and Post-Secret

Requests, basically ways of sending instructions. So let's take the GeT request

first. That's where

the diagram description gets encoded into the URL itself. Exactly. So that simple

example,

bob-alice.hell, hello, in PlantUML. Yeah. It gets compressed and encoded into this

string of characters

and becomes part of the URL, like geet-plantl-mells-vg followed by that encoded

string.

syskj2rkt3-coccanellerr1.io4 is a dose of 70,000 or something similar. Yeah,

something like that.

It uses deflate compression and then base64 encoding. Sounds complex, but the point

is it

packages your text neatly into the web address. But you don't need to do the

encoding yourself

necessarily, right? There are tools for that. Absolutely. The docs even show a

Python one-liner

to do it, but often you'd use a library or an integration that handles it. However,

there's

also the POST request method. Which is often simpler for users. Generally, yeah.

Especially

for longer diagrams. With POST, you don't stuff everything into the URL. You send

the diagram

source text, the type of diagram, and the output format you want, like SVG or PNG.

Usually as a

JSON object in the request body. So that Bob Assala sat hello example would just

look like.

Sending a little package with diagram source is the text. Diagram type is plantable.

Output format

is SVG. Precisely. Much cleaner, much more readable, especially when your diagram

description gets

longer. And you can even send plain text directly, apparently, with the right

headers. You can, yeah.

Setting the content type header to text plane, that may be the accept header for

the output format.

Or even put the output format in the URL path for a post C, like post T plantamalsvg.

Okay. So the

main point is flexibility. You can talk to Kroki using pretty much any standard web

tool or code.

Any HTTP client. Exactly. Browser, command line, like C or RL, scripting languages.

So how does it manage all those different diagram types then? Mermaid, plant UML,

GraphViz. They're all separate projects. Ah, that's down to its architecture.

It's quite clever and modular. There's a central server. It's actually a Java web

server acting

as the main entry point, the gateway. Okay. But then for many of the individual

diagram libraries,

it uses separate companion servers or sometimes Node.js command line tools. So when

a request

comes in for, say, mermaid, the main server passes it off to the specific mermaid

service.

Ah, so it's like a manager directing traffic to different specialists.

Exactly. It means they can add support for new diagram types relatively easily just

by adding a

new companion service without messing with the core gateway. That makes sense. Keeps

it nimble.

Very much so. It allows it to evolve as new tools pop up.

Right. So if someone's listening and thinking, okay, I want to try this,

what's the easiest way in? The absolute simplest way is just

go to croquis.io. They run croquis as a free public service right there.

Ready to use in the browser or through those API calls we talked about?

Yep. No installation needed. Just start sending requests

or use the simple interface they have on the site. Perfect for trying it out.

But what if you want to run it yourself? Maybe for privacy or internal use?

You could do that too. It's open source. Remember, you can self-manage it,

download the code, install it on your own server. The documentation mentions it

probably requires a bit of Linux know-how to set up smoothly.

Okay, so maybe not for total beginners to self-host, but the options there.

Right. But for just using it, that free service is fantastic.

And it's supported by sponsors like Exoscale providing servers, which keeps it

running.

And that commitment to being free and open source really stands out. MIT license.

Yeah, very permissive.

Available on GitHub for anyone to look at, contribute to.

And you can host it yourself with pretty minimal resources, apparently.

They even say on the site, crookie is never going away.

That's quite a statement. Shows confidence in the model.

It does. And that open approach really encourages community involvement.

The sources mentioned they're actively planning the future,

even have a questionnaire out asking for user input.

Ah, so they're listening to users.

Seems like it. It reflects that idea that more perspectives make things better.

Plus, they provide good resources, a cheat sheet, lots of examples.

Decent documentation makes it easier to get started.

So it's not just code thrown over the wall, it's an active project.

Definitely feels like a living project, yeah.

Okay, so stepping back a bit.

Beyond just making diagrams quickly, what's the bigger picture here?

Why does simplifying visualization like this really matter?

Well, knowledge is only useful if it's understood and can be applied, right?

Visuals are just incredibly powerful for that.

Croquis makes creating those visuals almost trivial.

And think about modern workflows.

You can actually store the text for your diagram right alongside your code in Git.

So the diagram becomes part of your version control.

Exactly.

Diagrams is code.

It means your documentation, your architecture diagrams,

can evolve right along with the system itself.

They stay up to date.

That's huge.

No more outdated diagrams floating around.

Hopefully fewer anyway.

It makes collaboration smoother, turns abstract ideas into something concrete and

shareable.

And it really lowers the barrier to entry, doesn't it?

It democratizes it.

You don't need to be a designer.

You don't need expensive software licenses.

Anyone who can write a bit of structured text can create a clear visual.

It empowers more people to communicate their ideas effectively, quickly too.

Yeah, speed seems key.

And think about those industries mentioned in the sources,

DevSecOps, healthcare, finance, manufacturing.

Right, lots of complex systems there.

Absolutely critical to understand workflows, architectures, processes in those

fields.

Kroki offers a simple, consistent way to generate those vital diagrams

across different teams, different projects.

So it promotes consistency as well.

And maybe even better understanding,

because you had to articulate it clearly in text first, like we discussed.

We've covered a lot of ground here on Kroki.

From what it is creating diagrams from text.

Using that unified API for tons of formats.

To how it works with HTTP requests, GET and POST.

And its modular architecture.

And how you can use the free service or self-host the open source tool.

It really boils down to efficiency, accessibility,

and making complex stuff easier to grasp.

Hopefully this deep dive sparks some ideas, maybe an aha moment,

about how text diagram could help you.

Yeah, it's a powerful concept.

So maybe think about it.

What's one complex idea or process you've struggled to visualize recently?

Perhaps Kroki is the tool to finally make that clear.

For yourself or for your team.

And before we wrap up, a huge thank you once again to our sponsor, Safe Server.

They focus on hosting software solutions and supporting digital transformation

journeys.

Check them out at www.safeserver.de.

Great stuff.

Until then, keep exploring, keep learning, and keep asking questions.

Until then, keep exploring, keep learning, and keep asking questions.