drawio-scribe

Turn a flowchart image into an editable draw.io diagram.

A coding agent reads a source flowchart and transcribes it into a small YAML file — each shape's position, size, colour, and connections, copied by hand with judgement. drawio-scribe then compiles that YAML into a .drawio document (and, optionally, a PNG preview).

There is no automated shape detection. The agent is the recognizer; this tool is a deterministic renderer. "Scribe" is the point: faithful hand-copying into a new medium.

Why

Auto-vectorizing a scanned flowchart is fragile and rarely pixel-accurate. For a finite set of pages that need to match a source exactly, a capable coding agent placing coordinates produces cleaner, fully-editable results. This repo gives that agent a stable schema, a reusable visual theme, and a fast render loop.

Install

pip install -e .          # installs PyYAML and the `drawio-scribe` command

Or just install the one dependency and run the module directly:

pip install pyyaml
python -m drawio_scribe.cli example

PNG preview export needs the draw.io desktop app. It is found automatically via PATH or common install locations; override with --drawio or DRAWIO_SCRIBE_DRAWIO.

Usage

# render one or more pages (bare name, filename, or full path)
drawio-scribe example
drawio-scribe page_01 page_02
drawio-scribe example --preview        # also write conversion/example_preview.png

# point at a different project / output dir / draw.io binary
drawio-scribe example --root /path/to/project --out build --drawio /usr/bin/drawio

Output lands in out/<name>.drawio; previews in conversion/<name>_preview.png.

Layout

pages/        per-page YAML you author          (the input)
themes/       reusable visual vocabulary        (default.yaml)
out/          generated .drawio files           (output)
conversion/   previews + scratch artifacts
images/       source reference images           (optional)
docs/
  PROCEDURE.md                    generic engine playbook (for the agent)
  conventions/<family>.md         rules specific to a source-document family
drawio_scribe/  the renderer

How it works

• Pages are data. Named-field YAML (shapes, edges, point_edges, lines, texts, lane) with explicit pixel coordinates. See docs/PROCEDURE.md for the full schema and pages/example.yaml for a comprehensive example.
• Styling is a theme. Colours, shape aliases, and edge routes live in themes/default.yaml. Swap the theme to support a different document family without touching the renderer.
• Routing is explicit when it matters. Ordinary connectors bind source→ target; tricky ones (diamond branches, loopbacks) use point_edges with exact coordinates. Per-edge exit/entry overrides handle off-default sides, so the theme keeps only generic, reusable routes.

Start here

New to a page? Read docs/PROCEDURE.md, then copy pages/example.yaml as a template.