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, a use-case diagram, an ER model, a data dictionary, a gantt, a milestone timeline or a lifecycle. 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, erDiagram, gantt, timeline and flowchart or graph sources are converted on paste, and you can export back to Mermaid. A gantt has one limit worth knowing: a plan with no start date cannot become Mermaid, because Mermaid's gantt has no relative axis and arch-lab will not invent a date. Its computed critical path does not travel either — Mermaid has nowhere to record one, and a hand-typed crit tag would be a claim rather than the arithmetic. The lifecycle has no Mermaid counterpart at all and none was invented: stateDiagram-v2 is a state machine — every transition that could happen — rather than one subject's actual history.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
Does it have a dark mode, and can I change how it looks?
arch-lab ships nine themes — Light, Paper, Pastel, Liquid glass, Dark, Midnight, High contrast, Blueprint and E-ink. A theme repaints the diagram, not just the page around it: node fills, connector ink, the canvas ground, and the SVG or PNG you export all follow the one you picked. Every palette is contrast-measured rather than a recolour, and E-ink has no colour at all — it tells the roles apart by texture, so a diagram still reads printed or projected in greyscale. The picker sits in the header on every page, your choice is kept in your browser, and a first visit follows your system's light or dark preference. Immersive view hides the site around the diagram for the same reason, so what is on the screen while you talk is the diagram and nothing else.Finished examples
Can I edit the diagram on the canvas, or only as text?
An arch-lab diagram is edited two ways. All ten notations are edited as source text; six of them — C4, sequence, flowchart, use case, ER and dictionary — are also editable on the canvas, where a drag writes a position or an order into that same text rather than into a private layout file. Either way the change lands in the same one-line-per-element text you review in a pull request. Which notations answer a drag is a property of their grammars rather than a roadmap — the next answer explains what each grammar has to write a drag into.The playground
Why does dragging work on some diagrams and not others?
A drag needs somewhere in the text to land. Four of the ten notations carry a per-element position — C4 model, flowchart, use-case diagram and ER diagram — so dragging one edits the text and the change survives a reload. Leaving that position out is still the normal case, which is why a diagram you have never dragged lays out exactly as it always did. Two are the halfway case — sequence diagram and data dictionary — with no coordinates but an ORDER, so a drag moves an element in time or across a column and it takes a neighbour's place rather than staying where you drop it. The remaining four work their layout out FROM the text — gantt chart, milestone timeline, lifecycle and decomposition tree — where columns come from the relationships, a dictionary is one table whose columns are measured across the whole document, a gantt's bars are placed by the calendar and the dependency graph, and a timeline's events and a lifecycle's states are placed by the order you wrote them in. A dragged box would be put back by the next render, and there would be no line to write it on. Change the text and the layout follows.Syntax reference

The .alab format

Which diagram kinds can arch-lab draw?
Nine, 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; use-case diagrams with actors, a system boundary and include or extend relationships; entity-relationship diagrams with keys and crow's-foot cardinality; data dictionaries of every field with its meaning, source and whether it is personal data; gantt charts of tasks, milestones and what each one waits on; milestone timelines of events grouped into the periods they happened in; and lifecycles of one named thing moving through ordered states, with the branches that leave that track.
Can arch-lab draw a Gantt chart?
Yes — it is the seventh of nine document kinds, called a gantt. How long each piece takes, and what can't start until it's done. It draws tasks with a duration, milestones as diamonds, sections, and the dependencies between them. The critical path and each item's float are computed from the dependencies rather than declared, so the picture cannot disagree with the arithmetic — which is also why there is no keyword for marking a task critical yourself. Mermaid gantt sources paste straight in.Write a ganttFinished gantt charts
Can arch-lab draw a timeline?
Yes — it is the eighth document kind. What happened when, and which period it happened in. It draws events as points on a spine, grouped into named periods, and it runs down the page rather than across so a long label has room to be read. Deliberately, it holds no durations, no dependencies and no status: if your work has lengths and prerequisites you want a gantt, and writing any of those into a timeline is refused by name with a pointer to it. Mermaid timeline sources paste straight in, and export back out again.Write a timelineFinished timelines
Can arch-lab draw a lifecycle?
Yes — it is the ninth document kind. What one thing went through, and where it can end up. It draws one named subject, the ordered states it passes through as dots on a spine, and the branches that leave that track — each of which either ends or rejoins an earlier state. It overlaps a flowchart on purpose and is deliberately smaller: there is no line between two states at all, because the track IS the order you wrote them in, and a branch may only return to a state the subject has already been in. If your picture is really steps and decisions that can go anywhere, write a flowchart — the grammar refuses every construct that would turn this into one, by name, with a pointer to it. There is no Mermaid dialect for this notation.Write a lifecycleFinished lifecycles
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.
If nothing is uploaded, how does Copy markdown put a picture in my README?
It cannot do it the way a share link does, and that is the trade. A share link keeps the model after the #, which browsers never send anywhere — but a README shows a picture through an image tag, and an image tag is a request. So the markdown you copy points at /api/render with the model in the query string, and that URL does reach our server: once when you test it, and again every time anyone opens the page holding the image. We store none of it — the URL is the only copy, exactly as with a link — but it does travel, it appears in request logs, and an expiring link's image expires with it. Nothing mints such a URL unless you press the button, and if you would rather not, copy the link instead: it shows the diagram live, with its motion and its paths.
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, MCP and skills

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 28 tools, covering all nine document kinds — including the two a gantt needs, which report the critical path and the dependency cycles a parse cannot see, and the two a lifecycle needs, which catch a subject that never terminates and states named as actions rather than conditions.Connect your agent
Can I use this without connecting an MCP server?
Yes. The same grammar ships as an Agent Skill — markdown files installed into your repository with `npx skills add raksitnongbua/arch-lab --skill alab`, or copied by hand if you would rather not run a CLI. Nothing connects and nothing runs: your agent reads the grammar the way it reads any other file, and writes .alab with its own editing tools. What a skill cannot give you is the verdict — a file cannot tell you whether what was just written parses. For that, paste it into the validator, or connect the server so the agent can check its own work. Plenty of people do both: the skill for everyday writing, the server for the check at the end.Install the skillCheck a document by hand
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