Exporting a C4 diagram from your agent: Mermaid or PlantUML

By the OrgGen AI team

An architecture export is never complete: the target grammar has a finite number of slots, and the model has more. This guide says which of the two C4 formats keeps what, what both leave behind, and why OrgGen tells you rather than letting you find out in an architecture review.

Two grammars, one difference

OrgGen exports an architecture diagram in two C4 grammars: Mermaid and PlantUML. The choice is not cosmetic. The two do not carry the same amount of information, and the gap comes down to a single thing.

mermaid-c4plantuml-c4
C4 type (person, system, container…)yesyes
Technologyyesyes
Trust boundaryyesyes
Component descriptionNO — droppedyes

The cause is in the macro itself. In C4-PlantUML, a container is written with four parameters (identifier, name, technology, description), and the fourth exists. In Mermaid, a node's label combines the name and the technology; there is no fourth slot in which to put the description.

What neither of them carries

Both grammars spend their three slots on the C4 type, the technology and the trust boundary. Everything your model carries beyond that stays in OrgGen, and you need to know that before treating the exported file as the source of truth.

  • Content blocks: notes, lists, action checklists, and links attached to a component.
  • People and their roles: who is responsible for which component.
  • A block's progress status (in progress, future, abandoned…).
  • Attached documents. This is structural, not a lack of room: a document lives outside the schema, so no diagram serializer ever sees it.
  • The project link to another OrgGen project. "This component is really a project in its own right" is not a notion C4 can express.
  • The block label, for lack of a fourth available slot.

None of these losses is a defect to fix: they are dimensions the target grammar cannot express. What would be a defect is not saying so.

The export tells you what it left behind

Every architecture export returns, next to the file, the list of what it could not carry, with the number of affected items in YOUR project.

The Mermaid C4 (flowchart) format does not carry the block descriptions (7 in this project).
The Mermaid C4 (flowchart) format does not carry the content blocks (12 in this project).
The Mermaid C4 (flowchart) format does not carry the progress status of blocks (4 in this project).
What the call returns, next to the diagram (example counts)

The count is not decorative: it covers what your project ACTUALLY contains. A dimension your schema does not carry produces no warning. A project with no documents is never warned that a document would not make it through.

Doing it from your agent

The export is a tool, available both in OrgGen's chat and from your own MCP client (for example Claude Desktop or a custom agent). The connector plugs into OrgGen's MCP entry point; the agent then discovers the tools, including the available architecture formats.

export_arch_diagram({ format: "plantuml-c4" })
Export, keeping the descriptions

The reverse path exists too: an architecture diagram can be IMPORTED into an OrgGen project, so you can start from a file you already have rather than a blank page. And because a remote agent cannot guess the product's rules, the MCP server hands it, on connection, the rules that apply to the diagram types actually present in the connected project.

Try it on your own case

Describe your situation in one sentence — OrgGen builds the diagram and runs the numbers.

Try it on your own case

← All guides