Skip to content
arch-lab

FAQ

Questions about arch-lab

What the format is, how it compares to what you already use, what leaves your browser, and what an AI agent is allowed to do. If the answer you need is not here, the last section says where to ask.

Getting started

What is arch-lab?
arch-lab is a browser-based editor for architecture diagrams written as plain text. You describe a system in a few lines and it draws it: a zoomable C4 model you can drill into level by level, a sequence flow you can click through message by message, a flowchart, or a use-case diagram. The text is a file you own, and git is the collaboration layer.Open a live diagram
Do I need an account?
No. There is no sign-up, no login and no user record. Open the playground and start typing — the worked example is already on screen.The playground
Is my diagram uploaded anywhere?
No. Parsing, layout and rendering all run in your browser, and the document never leaves it. The one request that touches a server is optional link expiry, which sends a SHA-256 hash of the compressed payload and gets back a signature — never the diagram itself.
What does arch-lab cost?
Nothing. There is no paid tier, no trial and no usage limit, and the source is MIT-licensed on GitHub.The repository

Deciding whether to use it

Why write a diagram as text instead of drawing it?
Because a drawn diagram cannot be reviewed. A .alab file has stable ids, one line per element and a deterministic order, so a pull request shows what changed in the architecture rather than a reshuffled binary. It also sits next to the code it describes, which is the only thing that keeps a diagram current. The trade is real: free-form drawing is faster for a one-off sketch, and this is not the tool for one.
How is arch-lab different from Mermaid?
Mermaid renders a diagram; this renders one you can present and drill into — zoom a C4 model level by level, step a sequence flow message by message, trace a flowchart as it draws. It is not an either/or, though: Mermaid pastes straight into the playground. C4Context, sequenceDiagram and flowchart or graph sources are converted on paste, and you can export back to Mermaid.Paste Mermaid into the playground
Can I get my work back out?
Yes, in five ways, none of which need this site: the .alab text itself, arch-lab JSON, Mermaid, SVG, and PNG rasterised at 2x. A multi-level C4 model exports as a ZIP with the levels numbered so they stay in drill order. There is nothing to migrate off, because there is nothing holding your file.
Is it good enough to present from?
That is what it is built for. Every theme is complete and contrast-measured rather than a palette swap, there is an immersive view for showing a diagram on a screen while you talk through it, and a share link carries the whole model inside the URL so the person you send it to needs nothing installed.Finished examples

The .alab format

Which diagram kinds can arch-lab draw?
Four, all in the same text format and the same editor: C4 models across the context, container and component levels; UML-style sequence diagrams with lifelines, activation, loops and alt fragments; flowcharts with terminators, guarded decisions and loops that hook back; and use-case diagrams with actors, a system boundary and include or extend relationships.
What is a .alab file?
One plain-text file holding one document. It is line-oriented and readable without this site — an element per line, ids you chose, and a deterministic order so two people editing the same model produce a diff you can read. The format is marked beta: it is in real use and stable in practice, but it is not yet frozen.The syntax reference
How do I check that a document is valid?
Paste it into the validator and you get a verdict located to the line and column, from the same parser the playground uses — plus the offending line quoted back. Every example in the syntax reference is checked against that same parser before release, so nothing documented there has drifted from what the parser accepts.The validatorThe syntax reference

Sharing a diagram

How can a share link work if nothing is uploaded?
The model is compressed and carried in the URL fragment — the part after the # — which browsers never send to a server. Whoever opens the link reconstructs the diagram locally from the link itself. Nothing is stored, so there is nothing to look up, expire by accident, or leak.
Do share links expire?
Only if you ask for it. Expiry is opt-in: choose a lifetime when you create the link and the site signs that expiry, which is what replaces the database an expiring link would otherwise need. A link with no expiry keeps working. A link that has expired says so plainly instead of showing a broken page.
Is there a size limit on a share link?
Yes — a URL has a practical ceiling, so a very large model will not fit in a link. When that happens the share panel says so at the point you ask for the link, rather than minting one that fails for whoever opens it, and it hands you the .alab file to send instead. The MCP tool refuses the same way, with the document text in its reply.

AI agents and MCP

Can an AI agent write arch-lab diagrams?
Yes, and it is half of why the format is plain text. Point Claude Code, Cursor or any MCP client at the server and the agent gets the two things it cannot guess: the exact grammar, and the real parser's verdict on what it just wrote. There are 14 tools, covering all four document kinds.Connect your agent
Can the MCP server change my files?
No. Every tool is read-only and there is no mutation API — the server validates, formats, converts and describes documents you hand it, and hands text back. Your agent writes the file with its own file tools, under whatever permissions you already gave it. The endpoint is also stateless and unauthenticated, so it holds nothing about you between calls.What each tool does

Still asking?

Open an issue on GitHub — that is where this project is actually read, and a question there tends to become either a fix or a new answer on this page. If your question is about the grammar, the syntax reference is more precise than anything here, and the validator will answer it against the real parser in one paste.

Open a live diagramAsk on GitHub