feat(diagrams): editable design language for architecture figures

[mihir-datazip]

What this adds

A diagrams/ directory holding one editable source of truth for our architecture figures, plus the tooling to keep them consistent:

Path	What it is
olake-architecture.drawio	12 diagram pages in one draw.io file. Page 00 is the legend.
olake-shape-library.xml	40 drag-and-drop components: shapes, a glyph set, and vendor marks
previews/pNN.svg	A rendered preview of every page — reviewable directly in this PR
tools/gen.py	The generator that emits the .drawio and the previews from the same component definitions
tools/build_icons.py, tools/icons.json	Vendor marks from simple-icons (CC0) and devicon, plus hand-drawn marks for Db2, S3, Iceberg and the JVM

Nothing else in the repo is touched — no blog or docs content changes here. The figures in the architecture deep-dive are still the old images; swapping them is a follow-up (see below).

Why

The nine images in the architecture deep-dive were each generated separately, so no symbol survived from one figure to the next:

• a funnel meant "classify" in one image, "buffer" in the next panel of the same image, and "the driver itself" in another
• a CDC reader was a person icon, then an eye, then a plain grey rectangle — in three consecutive figures of the same series
• state was a floppy disk twice and a document grid once
• green = committed existed in exactly one image
• vendor logos appeared as full-colour collages at mixed sizes, next to grey clip-art, with three different arrow styles in one frame

Individually each image was fine. As a set they taught the reader a vocabulary and then broke it on the next scroll.

The design language

Defined once on page 00, obeyed by the other eleven:

• Colour is semantic, never decorative. Blue #193AE6 = OLake compute · slate = external systems · green = durable/committed · amber = state and bookkeeping · rose = failure and retry. Each is a 2px stroke over a light tint of the same hue.
• One meaning per shape. Anything that stores data is a cylinder (source DB, Kafka, catalog); object storage is a bucket; a destination table is a table card with a grid glyph; anything OLake runs is a UML component; a Go interface is an interface box with «interface», an I badge and real method() signatures; an ordered log is a segmented tape with real events in its cells.
• Edges carry meaning. Solid slate = data flow, dashed amber = state/metadata, bold green = atomic commit, red = failure path. Labels sit beside the line, never on an opaque badge.
• Real values everywhere — ctid (0,1)–(4,0), 0/1A2B3C4D, id 2 · Bob, actual Kafka offsets. Never placeholder boxes.
• A fixed glyph template. Twenty line icons (classify, chunks, types, state, buffer, schema, commit, lock, retry, pin, log, parallel, dial, writer, handoff, clock, discover, table, file, delete). Blocks pick from the set rather than inventing an icon each time.

Conventions were cross-checked against published guidance (C4 notation, draw.io's consistency guide, Ilograph's diagram-mistakes series, Excalidraw's palette formula) and against how the field actually draws these concepts — Kafka's log-anatomy figures, Netflix DBLog, PeerDB, Debezium's incremental-snapshot post, Confluent's DLQ post, Fivetran's hybrid deployment diagram.

How we unify diagrams across the rest of the docs

This is the part worth discussing in review — the file is only useful if the next person reaches for it.

1. Start from the library, not from a blank canvas. Open diagrams/olake-architecture.drawio, then File → Open Library From → Device → olake-shape-library.xml. Every shape a data-pipeline diagram needs is already there — source systems with vendor marks, readers/writers, change-log tapes, chunks in four states, state files, destination tables, the glyph set. A new figure is assembled, not drawn.

2. Page 00 is the contract. It is the legend and the reference sheet: the palette with its meanings, every component with its label, the interface notation, the edge grammar, the glyph template and the rules. Adding a new concept means adding its symbol to page 00 first, so the vocabulary grows deliberately instead of drifting.

3. Two ways to change things, and they don't mix.

• One-off tweaks — edit the .drawio directly (VS Code with hediet.vscode-drawio, app.diagrams.net, or the desktop app). Diffs land in git like any other file.
• Systematic changes — edit tools/gen.py and run cd diagrams/tools && python3 gen.py. Every component is one Python method that emits draw.io XML and preview SVG together, so changing component() or the HUE table restyles all twelve pages at once. Python 3 and the checked-in icons.json are the only requirements.
• The catch, documented in the README: regenerating overwrites hand edits. Keep changes in the generator, or stop regenerating once you start editing by hand.

4. One export recipe so figures look the same wherever they land: File → Export as → PNG, zoom 200%, border 0, white background (not transparent — the docs render on light and dark themes), then cwebp -q 82 into static/img/blog/....

5. Where this scales next. The same vocabulary covers the connector docs, the Iceberg writer posts, and the exactly-once deep dive, which today each carry their own one-off images. Anything new gets added as a page in this file rather than a fresh canvas, so the whole documentation set converges on one look instead of diverging per author.

Reviewing this PR

Open diagrams/previews/p00.svg first — it is the legend, and it explains every choice the other pages make. Then p01 (pipeline overview), p02 (the interface diagram), p08/p09 (the worked examples that follow real rows from source to destination).

Follow-ups, not in this PR

• Export the twelve pages and replace the images in blog/2026-07-22-deep-dive-into-olake-architecture.mdx (page 11 also covers the mermaid write-path block, if we want that visually consistent too).
• Decide whether the two remaining mermaid blocks in that post stay as mermaid or move into the file.
• Apply the language to the connector docs and the other Iceberg posts.

Draft while the language itself is up for discussion — the shapes and rules are the thing to argue about now, before figures get exported against them.