A free block diagram generator that starts from text

A block diagram generator turns a short text file into a grid of boxes. You set the column count, you name the blocks, and the layout stays where you put it instead of wandering off to satisfy a graph layout.

I use this when the rows themselves mean something. A page on top of an API on top of a database. Three clients across the top and three services under them. The picture is a stack or a table, not a story with a yes and a no. If you came for arrow syntax and decisions, you wanted a flowchart, and a flowchart will move these boxes the moment you add an edge. That's the whole reason block-beta exists.

The block diagram syntax page is the token reference. I'm not going to replace it. This page is the judgment: when a grid is the picture, how columns actually wraps, and the mistakes that look like a renderer bug.

A grid, not a story

block-beta opens the diagram. The next decision is columns. That number is the width of a row. Then you list blocks. With columns 1, each block is a row, so the file reads top to bottom in the order you typed. With columns 3, the file fills left to right and then wraps. You are writing the layout. You are not describing a graph and hoping.

A block is an id and a label. api["API"] keeps the id api stable when the label changes to "Public API". Arrows are allowed and they're optional. On a layered picture the vertical order already says the thing above talks to the thing below. Add an arrow when the neighbor isn't obvious. Skip arrows when every neighbor is connected, or the grid disappears under the lines.

Labels stay short. The block is a cell, not a paragraph. Put the explanation in the doc under the figure. I learned this by stuffing "handles checkout, tax, and receipts" into a cell and watching the row become a banner. The banner was my paragraph, displaced.

This is still text in git. A teammate can review a one-line change to columns and see the wrap change in the preview. They cannot review a dragged rectangle with the same confidence, because the drag doesn't say which row it thought it was on.

Why a flowchart will move the boxes

I try this mistake about once a year. I want a tidy three-tier picture, so I write a flowchart with the web on top, the API in the middle, and the database at the bottom, and I use invisible links to pin them. It works until I add a cache. The layout engine has a new node and a new idea about ranks. The database slides. The API sits beside the web. The picture is still "correct" as a graph and wrong as a stack.

That's not a bug. A flowchart is a graph. Edges are the meaning, and position is a consequence. A block diagram reverses that. Position is the meaning, and edges are a hint. If I need both a strict grid and a rich set of decisions, I draw two figures. I don't torture one of them into the other.

The moment I notice myself adding a link "so it stays put," I switch the keyword to block-beta and delete the fake links. The preview gets boring. Boring is what I wanted from a stack.

columns 1 is a stack

One column means there is no "beside." The next line is the next row. I use this for a dependency direction I can narrate downward: the browser calls the API, the API calls the database. If the real system also lets the browser call the database, the stack is now a lie, and I should add an arrow or stop using a single column.

block-beta
    columns 1
    browser["Browser"]
    api["API"]
    db["Database"]

columns 1 is the whole layout decision. The browser can't drift next to the API, because there is no next-to. Renaming api["API"] to api["Public API"] doesn't move the box. Adding a cache as a fourth line puts it under the database, which is probably wrong. With one column, position is list position. Insert the cache where the layer actually sits.

I don't add arrows on this one. The stack is the sentence. An arrow from every box to the next would say the same thing in a louder voice, and it would start to look like the flowchart I just abandoned. If a reader can't point at a row and name the tier, the labels are wrong, not the arrows.

A single column is also the right generator output when someone describes "layers" and the model, or you, start drawing peers. Peers need a wider row. Layers need this. I re-read the noun. "Above" and "below" mean column 1. "Beside" and "also" mean a wider column count.

columns 3 is a row that wraps

Three columns fill a row and then wrap. Six blocks become two rows of three. Four blocks become a row of three and a leftover. The leftover is the surprise. People see it and think the layout engine dropped a box. It didn't. The column count is the row width, and you handed it a list that doesn't divide evenly.

block-beta
    columns 3
    web["Web"]
    ios["iOS"]
    android["Android"]
    gateway["Gateway"]
    billing["Billing"]
    catalog["Catalog"]

The first row is clients. The second row is services behind them. That reading only works because I grouped the lines that way. If I insert admin["Admin"] after web, everything after it shifts, and iOS wraps onto the service row. The picture is still a valid grid. It's a false architecture. With columns 3, insertion is a layout change, not a harmless append. I leave a comment in the markdown above the fence that says "row 1 clients, row 2 services," so the next edit doesn't "tidy" the order alphabetically.

I could have used columns 1 twice in two diagrams, clients and services separately. I use one diagram when the relationship is "these clients sit on these services" and the grid is the relationship. I split when the two rows are different stories that happened to share a page.

Arrows are still optional here. A line from every client to every service is a complete bipartite graph, which is a polite way of saying a mess. If only the web client talks to billing, draw that one arrow. If all of them talk to the gateway and the gateway talks downward, say that in a sentence and consider whether you wanted the stack from the previous section instead. A 3-column grid that needs a paragraph of exceptions is the wrong grid.

When you want the grid

I want the grid when a reviewer will say "that box is in the wrong row." Row and column are the claims. A deployment view with edge, application, and data as rows is that claim. A comparison of three clients across the top is that claim. A picture of a circuit, in the loose sense of blocks and not in the sense of a SPICE deck, is that claim if the arrangement is conventional and the labels are the components.

I don't want the grid when the next sentence is "if the check fails, go back." That's a decision, and a block has no diamond. You can put a question mark in a label. You cannot make the grid branch. People try, by placing the failure box to the side. The side is just the next cell. A reader who expects flowchart semantics will invent a branch you didn't write. Don't teach them that.

I don't want the grid for a sequence of calls either. Time goes down a sequence diagram as messages, not as a column of participants you happened to stack. If the interesting fact is the reply, block-beta will hide it.

The system layers template is the starter I open when I already know I want tiers and I don't want to invent the ids. I replace the nouns and I delete rows that aren't in this system. A template is not a description of your company. It's a grid with someone else's labels.

Cells are labels, not paragraphs

The generator, human or AI, will try to be helpful by writing sentences into cells. "Service that owns the cart and talks to tax" is a design note. It will also force the column wider than its neighbors, and the grid stops looking like a grid. I cut cell text to one or two words, then I write the note under the figure where a sentence is allowed to be a sentence.

Ids stay boring. billing, catalog, gateway. If the AI returns Billing Service (US) as an id, the parentheses will often break the line unless they're inside quotes on the label. The form is billing["Billing (US)"]. The id doesn't get the parentheses. I fix that before I discuss whether the US boundary belongs on this picture at all. Usually it belongs on a different picture, and this one should say Billing.

The cheat sheet has the block line on one page so I don't reopen a long syntax article to remember columns. I still reopen the syntax page when I want a span or a nested block. This article doesn't try to be that page. If you need a block that stretches across two columns, look it up rather than guessing with a colon you half remember. A guessed span is how a tidy row becomes a staircase.

Layout bugs that look like a glitch

These render. They're still wrong, or they fail in a way that looks like the tool lost a box.

1. columns 3 with four blocks, and a complaint that the fourth "wrapped by itself." The wrap is the column count. Use columns 1 if you wanted a stack, or add the blocks that complete the row.
2. Editing the id when you meant to edit the label, then leaving arrows pointed at the old id. api["API"] keeps the arrows alive. Renaming the id to publicApi and not the arrows deletes the relationship and keeps a confident grid.
3. An arrow between every pair, so the grid you set is hidden. Add an arrow only where the stack doesn't already show the relationship.
4. Alphabetical sorting of the lines because a formatter, or a teammate, likes order. In this diagram, order is coordinates. Sort it and you moved production next to the browser.
5. Using a flowchart keyword out of habit, flowchart TD, then wondering why columns 1 is a syntax error. columns belongs to block-beta. The other keyword will try to read it as a node.

The fifth one is my muscle memory. I start typing flowchart because most of my diagrams are flowcharts. The preview's error is the correction. I don't "fix" it by deleting columns and drawing arrows. That gives me the picture I already know how to regret.

A sixth, from a review last month. Someone put the database on the first row because they think about data first. The rest of the company reads top as "closest to the user." Both conventions work. Mixing them in one doc doesn't. Pick a convention in the paragraph above the figure and stick to it for the file. I read top as the user unless the title says I'm drawing from the data outward.

From a one-line description to a file

The AI block diagram generator will stack components from a short description. I use it when I have the nouns and I don't want to fight a blank file. I name the column count in the prompt. "block-beta, columns 1, three layers: browser, API, database. No arrows. No cache." If I forget the column count, I often get a flowchart, because that's the diagram a vague "diagram of our stack" tends to become. Say the keyword.

You get five free AI uses in total. A block diagram is a reasonable spend when the grid is real and the labels are known. It is a bad spend when you haven't decided whether you wanted rows. Decide, then generate, then fix columns by hand in the editor and watch the wrap. Hand editing a column count is one line. Spending another generation to change a 1 to a 3 is how the free uses disappear.

After it renders, I check two things only. Does each row mean one thing? Did any block appear that I didn't name? The second check is the one people skip because the picture looks finished. A finished-looking cache you don't run is still a cache in the document. Delete the line.

If this grid is really a schematic in the loose sense, the notes on a schematic diagram creator and on text that becomes a schematic are the neighbors. I keep those separate from a service stack. A schematic reader expects component conventions. A service stack reader expects tiers. Don't mix the metaphors and then add AWS icons on top because the boxes felt plain. Mermaid AWS diagrams are their own problem, with their own icons and their own lies. A block labeled "database" is enough until you actually need the service name.

The block syntax examples are where I go for more shapes of block-beta once this stack and this 3-column grid make sense. More examples won't fix a wrong column count. They'll give you a wider menu of grids to misuse.

Open the editor, set columns before you name the boxes, and read the picture as rows. If you can't say what a row means, delete the diagram and write the sentence you were hoping the grid would imply.