A `.draw` file is an Excalidraw scene stored as a file in your workspace. You can sketch one by hand, or give Monofile mermaid and get back an editable diagram with shapes and arrows you can drag.

## What a `.draw` file is

It is a normal text file whose contents are an Excalidraw scene in JSON. Create one the way you create any file, by naming it with a `.draw` extension, and it opens in a full Excalidraw whiteboard: rectangles, ellipses, diamonds, arrows, freehand, text, colours and layers.

It is a file like any other: every write captures a version, you can share it by link, it shows up in backlinks when a note points at it, and an agent can read or rewrite it.

Saving is automatic. The board writes shortly after you stop drawing, and each write captures a version.

## Generating a drawing from mermaid

Nobody has to write Excalidraw JSON by hand. Give Monofile mermaid, piped in or read from a file you already have, and the server converts it:

```bash tab="From stdin"
echo "graph TD
  Client[Web client] --> API[API gateway]
  API --> Svc[Ingest service]
  Svc --> Q[(Queue)]
  Q --> W[Worker]
  W --> DB[(Postgres)]" | monofile diagram /design/ingest.draw
```
```bash tab="From a file"
monofile diagram /design/arch.draw --from ./arch.mmd
```

Agents get the same conversion as the `create_diagram` tool, and the built-in assistant uses it when you ask for a diagram. The path must end in `.draw`.

What comes back is not an image. Every box becomes an Excalidraw rectangle, every arrow an Excalidraw arrow, every label a text element bound to its shape. Open the result and you can move a node, recolour a group, add an annotation by hand, and delete the one box that was wrong, all without touching the mermaid.

## The five diagram types that convert

| Type | Write it as | Use it for |
|---|---|---|
| Flowchart | `graph TD` or `graph LR` | Architectures, data flows, pipelines, decision paths |
| Sequence | `sequenceDiagram` | Interactions over time |
| Class | `classDiagram` | Types and entities with fields and relationships |
| Entity relationship | `erDiagram` | Database schemas and cardinality |
| State | `stateDiagram-v2` | Lifecycles with named transitions |

Flowcharts take the full dialect, including `subgraph ... end` blocks for grouping and `classDef` for colouring. Anything outside these five, such as gantt, pie, mindmap or timeline, fails with an `UNSUPPORTED_TYPE` error.

> [!WARNING]
> Two things that trip people up:
>
> - **Quote punctuated labels.** `G["Identity provider (OIDC)"]` works, `G[Identity provider (OIDC)]` fails the parse, because the bracket reads as shape syntax. Monofile repairs the common case automatically and tells you it did, but quote the label yourself to be sure.
> - **Split before it sprawls.** Past roughly 25 nodes a diagram stops being readable. Use an overview board plus two detail boards in place of one large graph.

A parse failure reports the line number. Source is capped at 50 KB.

## The mermaid stays with the file

A generated drawing records the mermaid it came from, and the diagram type, inside the file. Two things follow:

- **Regeneration.** An agent can read the source back, change three lines, and regenerate the drawing.
- **Divergence is recorded.** When a person edits the board by hand, Monofile re-serialises the file from the shapes, and the file no longer claims that the recorded source describes it.

## Reviewing a change to a drawing

A text diff of a diagram is useless. The JSON is machine-generated and every conversion mints new element ids, so a one-box change diffs as the entire file.

When an agent changes a `.draw` file, the review shows you a picture instead, in three views:

| View | Shows |
|---|---|
| Diagram | The rendered board, with an After and Before flip so you spot the difference by toggling |
| Source | The mermaid that produced it, as a small readable diff |
| Raw | The underlying JSON diff, as an escape hatch |

Keep and revert sit on the same card, so accepting or rejecting a diagram change is one click.

## Next steps

:::cards
- [[Diagrams]] — Mermaid in markdown, and turning mermaid into an editable drawing.
- [[Canvas Boards]] — Spatial boards of live file nodes, notes, links, groups and labelled edges.
- [[Reviewing Changes]] — The diff view and the changeset card: keep or revert everything an agent touched.
- [[Supported File Types]] — The full extension to editor map, and what each editor can do.
:::