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.
Join us next time for another deep dive.
Until then, keep exploring, keep learning, and keep asking questions.