Drawing data models

A .drawio entity-relationship diagram in the same visual language as the other drawing-* skills: light page, white tables with hairline borders, Google's palette on the relationships.

Build it with erd_drawio.py (this directory). Check it with check_routing.py. Look at it with preview.py.

Where the files go

Everything this skill produces lives in one folder, never loose in the project root:

docs/diagrams/
  billing-schema.py             # the script that builds it
  billing-schema.drawio         # the diagram
  billing-schema.preview.svg    # what you looked at

Use the folder the user names. Otherwise put it under docs/diagrams/ when the project has a docs/ directory, and diagrams/ at the project root when it does not — the build script, the .drawio, and any preview or PNG together. write() creates the folder if it is missing, so f.write("docs/diagrams/billing-schema.drawio") is all it takes, and preview.py writes the SVG beside its input.

Never leave a build script, a .drawio or a preview in the project root, and never write outside the project you were pointed at. One folder, named files — a diagram whose script sits next to it can be regenerated; one scattered across a repository root cannot be found again.

The output contract

1. Every relationship carries its cardinality. rel() requires it. A line between two tables that does not say one-to-many or many-to-many states that the rows are related without saying how, which is the only thing the reader came for.
2. Every connector routed — direct=, corridor= or points=. No default.
3. check_routing.py reporting 0 FAIL.
4. A foreign key's line meets the key. orders.at("user_id", "L") is a face fraction level with that field, so the line lands on the row it is about instead of the middle of the table.

The pieces

from erd_drawio import Model, L, R, T, B, WEAK

m = Model("Orders", "postgres · public schema")
users  = m.table("users",  ["id PK", "email UNIQUE", "created_at"], col=0, row=0)
orders = m.table("orders", ["id PK", "user_id FK", "status", "total_cents"],
                 col=1, row=0)

m.rel(users, orders, "one-to-many",
      exit=users.at("id"), entry=orders.at("user_id", "L"), direct=True)

Columns are plain strings. A trailing PK, FK, UNIQUE, NULL or INDEX is read off the end and set in blue on the right of the row, so the source stays a list of columns rather than a table of markup.

colour=WEAK, dashed=True is for a link the database does not enforce — a column joined by convention, an id stored in JSON. Saying so on the picture is cheaper than finding out later.

Geometry

The page measures itself from the tables. width=/height= are a floor.

Before handing it over

S=~/.claude/skills/drawing-data-models
python3 "$S/check_routing.py" docs/diagrams/model.drawio        # must report 0 FAIL
python3 "$S/preview.py" docs/diagrams/model.drawio              # writes docs/diagrams/model.preview.svg
rsvg-convert -w 1400 -o docs/diagrams/model.png docs/diagrams/model.preview.svg

The preview draws plain arrowheads rather than crow's feet — draw.io renders the real ER ends from the same file. That is why the cardinality is also written on the line: the words survive both renderers, and a screenshot in a document.

Common mistakes

preview.py writes a plain SVG — open it in any browser if you have no rsvg-convert. The PNG step is for pasting into a document, not for looking at it.