Why I built Archdocs

Put a Payments API box in a checkout diagram, then copy it into a billing diagram. Rename the service and you now have separate labels to find and change, with nothing connecting them except your memory.

That's the problem I built Archdocs around. I want a service to keep its identity when it appears in another document. Copying its picture loses that connection.

A name should belong to the service

In Archdocs, I can create a Payments API object and reference that object in each document that needs it. The reference points to an ID. When I rename the object, its references show the new name. An ordinary rectangle with text stays an ordinary rectangle with text.

This distinction also gives me somewhere to attach the service's own documentation. A service object can hold documents about its API or internals, while a higher-level diagram refers to the service without copying all of that detail into the overview.

The dependency graph comes from documented relationships between references. The object's Used in view shows where it appears. Before changing a shared database, I want to look at those documents and see what assumptions they make about it.

There's a limit built into that sentence: documented relationships. An undocumented dependency won't appear because I wish it did. A graph can look complete while it's missing the call that will break a migration. I still have to check the model against the code and the people responsible for it. That's the maintenance problem behind docs rot.

I wanted to keep the canvas

Text is useful when I'm reviewing a change. A canvas is useful when I'm working out what the change should be. I wanted both ways of working on the same document.

Archdocs uses a fork of Excalidraw. An ERD entity holds typed rows, and a relationship can attach to a column. An API endpoint holds protocol details. A sequence diagram holds participants and ordered messages. Those structures give the editor information that a group of shapes and labels doesn't contain.

That decision carries maintenance work. Canvas drawing and SVG export have separate renderers. Text wrapping has to agree with measurement, or an exported endpoint card can put its text outside its bounds. The post about the Excalidraw fork covers those details.

For a temporary sketch, freehand boxes are often enough. I don't want to require a catalog entry before someone can draw a possible design. Objects are useful when the same thing needs to appear in documents that will be maintained separately.

YAML gives the document an editable source

The DSL describes nodes and relationships in YAML. The compiler measures the nodes, lays them out and emits canvas elements. Explicit node IDs keep an element's identity stable when the document is compiled again with the same document ID.

The hosted MCP server gives an agent access to that source. It can read a document, get the schema, validate YAML and submit an edit for compilation. I want an agent adding a service to reuse an existing database object, so the new diagram refers to the database that's already documented.

A valid edit still needs review. YAML validation catches a missing relationship target; it can't tell me whether checkout actually calls billing. The earlier post on architecture diagrams going stale describes that gap between a readable picture and an accurate system description.

What I want people to try

Archdocs is open for signups now. I don't have customer results to report. I have an editor and a model for keeping shared objects connected, and I want to see where that model makes documentation harder than it needs to be.

The free editor works without an account. Try an ERD with a relationship attached to a column, then move the entity. If you want to keep documents in a workspace, you can start free.

I'm especially interested in the point where you'd stop using an object and draw a plain box instead. That boundary decides how much structure the editor should ask you to maintain.