How it works

Schematlas reads the diagrams and docs in your repository, adds what those formats cannot hold, and writes every change back to the same files.

The repository is the source of truth

A Schematlas project points at a folder. Everything it shows comes from files in that folder, and every change you or your agent make is written back to them. There is no export step and no copy in a database: open the same files in VS Code, on GitHub or in draw.io and you see the same thing.

WhatWhereFormat
Diagrams you already haveanywhere in the repositoryMermaid (.mmd, .mermaid), draw.io (.drawio, .dio), DBML (.dbml), Mermaid blocks in Markdown
Diagrams made in Schematlas.schematlas/diagrams/Mermaid
Wiki pages.schematlas/wiki/ and .schematlas/Markdown
Saved database schemas.schematlas/schema/DBML
Navigation.schematlas/toc.yamlYAML
Arrangements you made by dragging.schematlas/layout/JSON

Adding data to existing formats

Mermaid, draw.io and DBML describe boxes and arrows. Schematlas needs a little more: which code a node stands for, a note, a kind, a color, the commit it was last checked against. It stores that inside each file, in a place the original tool ignores:

  • Mermaid: comment lines, %% @schematlas node api code=src/api.rs:12-80.
  • draw.io: the cell's own custom properties, schematlas-code, schematlas-note, which draw.io shows under Edit Data.
  • DBML: comment lines, // @schematlas node public.orders note="Customer orders".

The file still renders in Mermaid Live, draw.io or dbdiagram.io, and diffs stay readable. See Annotations for every key.

Edits keep your text

Schematlas edits a file by patching the part that changed, not by regenerating it. Your formatting, comments, ordering and styling survive. A node you rename changes one label; a note you add is one comment line.

Every write is a compare-and-swap on the file's content hash: if the file changed on disk since Schematlas read it — an editor, a git pull, your agent's own tools — the write is refused and the latest version is shown instead. Changes made outside the app appear in the open window.

Layout

Diagrams without saved positions are laid out automatically with the same layered algorithm Mermaid uses, so they stay clean as they grow. Drag a node and the diagram switches to your arrangement, saved beside the file in .schematlas/layout/ — the Mermaid source itself is untouched. Tidy up deletes that arrangement and returns to automatic layout.

draw.io files keep their own geometry: moving a node there moves it in the file.

Agents, with review

Your coding agent reads the code with its own tools. To change documentation it uses Schematlas tools — write_diagram, edit_diagram, write_doc, write_toc — which validate the proposal and open a review in the app. Nothing is written before you allow it, whatever permission mode the agent runs in. See Agents.

Edit this page