feat(docs): interactive DBML ER diagram for the database schema#545
Merged
Conversation
The schema reference had only per-schema Mermaid snippets. This adds a full, navigable ER diagram of all 60 tables, generated from the same DDL parse — no database, no system Graphviz, so it runs in CI with Node + Python only. - generate-schema-docs.py also emits docs/reference/schema.dbml: schema- qualified tables tinted by schema via headercolor (not TableGroups, so the renderer packs the mostly-disconnected tables into a compact block), column types/PK/NOT NULL/UNIQUE flags, table/column comments as notes, and FK edges as Refs. Doubles as a portable artifact you can paste into dbdiagram.io. - render-schema-diagram.mjs renders that DBML to SVG via @softwaretechnik/dbml-renderer + @aduh95/viz.js (Graphviz-wasm), injecting Graphviz `pack` to tile the layout ~square, then wraps it in a self-contained viewer: pan, zoom-to-cursor, table search, click-to-trace-relationships, and light/dark theming (recolors only the two theme-sensitive baked SVG colors via CSS variables + attribute selectors; schema header colors stay fixed). - schema.md embeds the viewer (iframe) and links the full-screen page + the DBML source; the per-schema Mermaid diagrams stay as the GitHub-native fallback where iframes don't render. - Wired into `make docs-schema` and the docs deploy workflow. Verified with a full mkdocs build: the standalone page and DBML publish as siblings and the relative embed path resolves under directory URLs. Claude-Session: https://claude.ai/code/session_017Her5fGimBvtzYD4q9tNnf
Follow-up to the code review of the interactive ER diagram: - Declare @aduh95/viz.js as a direct dependency — the renderer script requires it directly rather than relying on it being hoisted transitively. - Guard the Graphviz `pack` injection: throw if the `rankdir=LR;` token isn't found, so a renderer format change fails loudly instead of silently emitting an un-packed vertical strip. - Assert the two theme-sensitive baked colors exist in the rendered SVG before building the page, and drive both the assertion and the viewer's CSS from the same BAKED_CELL/BAKED_INK constants — a renderer palette change now fails the build instead of rendering unreadably in dark mode. - Single-source the schema legend: read headercolor values back from the DBML instead of a second hardcoded map that could drift from the diagram. - Use `npm ci` (Makefile + workflow) so a dependency bump can't be skipped by a stale node_modules guard and the lockfile stays authoritative. - Fix stale output paths in the renderer's header docstring. Regenerating produces byte-identical schema-erd.html (output preserved). Claude-Session: https://claude.ai/code/session_017Her5fGimBvtzYD4q9tNnf
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds a full, navigable ER diagram of all 60 control-plane tables to the Database Schema reference — generated from the same DDL parse the reference already uses. No database, no system Graphviz; runs in CI with Node + Python only.
How
generate-schema-docs.pyalso emitsdocs/reference/schema.dbml: schema-qualified tables tinted by schema viaheadercolor(color instead of clusters, so the renderer packs the mostly-disconnected tables into a compact block), types + PK/NOT NULL/UNIQUE flags, comments as notes, FK edges asRefs. Doubles as a portable artifact — paste into dbdiagram.io.render-schema-diagram.mjsrenders it to SVG via@softwaretechnik/dbml-renderer+@aduh95/viz.js(Graphviz-wasm), injecting Graphvizpackto tile ~square, then wraps it in a self-contained viewer: pan, zoom-to-cursor, table search, click-to-trace-relationships, light/dark toggle (recolors only the two theme-sensitive baked colors via CSS vars + attribute selectors).schema.mdembeds the viewer (iframe) + links the full-screen page and DBML source; per-schema Mermaid diagrams remain as the GitHub-native fallback.make docs-schemaand the docs deploy workflow.Verification (local)
make docs-schema→ 60 tables, 37 FK edges, all three artifactsdoclint --enforce-adrs✓ ·link_check --fail-on-broken✓mkdocs build✓ — standalone page + DBML publish as siblings; the../schema-erd.htmlembed resolves under directory URLs (no warnings)Follows the two CI hotfixes (#543, #544) that got
maingreen first.https://claude.ai/code/session_017Her5fGimBvtzYD4q9tNnf