Evidence-backed ERD diagrams and schema diff reviews from real code.
Bluewright is a local-first CLI for database schema visualization and pull request review. It reads a repository, extracts durable structure from source files, and writes evidence-backed ERD diagrams that can be reviewed in a browser or compared in CI.
The current prototype focuses on ERDs. It extracts database models from common schema sources, then produces:
- normalized JSON IR with source evidence
- Mermaid
erDiagram - source inventory reports that show which files each extractor used
- interactive HTML viewer with search, evidence, pan, zoom, fit, and focus
- ERD diff reports for baseline, branch, repository, or GitHub PR review
The longer-term direction is broader than ERDs: architecture maps, dependency graphs, flowcharts, state diagrams, and agent-assisted diagrams from real codebase context.
Install the CLI from npm:
npm install --global bluewrightFor local development, clone the repo, install dependencies, and link the CLI:
npm install
npm linkGenerate an ERD from a local repository:
bluewright erd /path/to/repo
bluewright erd /path/to/repo --agent claude
bluewright erd /path/to/repo --agent codex --out ./erd-outCompare ERDs:
bluewright erd /path/to/repo --compare ./main-erd.json --fail-on breaking
bluewright diff ./main-erd.json ./branch-erd.json --out ./erd-review --comment-file ./comment.mdReview GitHub repositories and pull requests:
bluewright repo https://github.com/org/repo --out ./repo-erd
bluewright pr https://github.com/org/repo/pull/123 --out ./pr-erd-review --github-step-summaryNPM scripts are also available during local development:
npm run repo -- https://github.com/org/repo --out ./repo-erd
npm run pr -- https://github.com/org/repo/pull/123 --out ./pr-erd-review
npm run erd -- /path/to/repo
npm run erd -- /path/to/repo --agent claude
npm run erd -- /path/to/repo --agent codex --out ./erd-out
npm run erd -- /path/to/repo --compare ./main-erd.json --fail-on breaking
npm run diff -- ./main-erd.json ./branch-erd.json --out ./erd-review --comment-file ./comment.mdOutputs:
erd.json: normalized diagram IR with evidence.erd.mmd: MermaiderDiagram.erd.html: HTML viewer with search, evidence, pan, zoom, fit, and focus.source-inventory.json: extractor-by-extractor file and count report.source-inventory.md: human-readable inventory summary.erd-diff.json: normalized ERD change report.erd-diff.md: PR-friendly Markdown review summary.erd-diff.html: offline visual diff report with a full ERD map that colors changed entities, fields, and relationships.
When --out is omitted, Bluewright writes under .bluewright/ in the target
repository or current working directory.
For GitHub pull requests, pass the PR URL directly. Bluewright checks out the PR base and head revisions, generates both ERDs, and writes the visual diff report.
npm run pr -- https://github.com/org/repo/pull/123 --out ./pr-erd-review --fail-on breakingThe PR output directory contains base/erd.*, head/erd.*, and the root
erd-diff.* report files. For private GitHub repositories, set GITHUB_TOKEN
or GH_TOKEN before running the command.
For GitHub repositories, pass the repo URL directly to generate the current ERD.
npm run repo -- https://github.com/org/repo --out ./repo-erdUse erd --compare <erd.json> to generate the current repository ERD and compare
it against a baseline. Use diff <base> <head> when both IR files already exist.
These JSON-based commands are useful in CI pipelines that already cache ERD IR.
Change impacts:
breaking: likely incompatible schema change, such as removed tables/fields, column/type changes, or stricter nullability.review: relationship, uniqueness, naming, or other changes that need human review before merging.safe: additive or compatibility-oriented changes.
For CI, add --fail-on breaking, --fail-on review, or --fail-on any.
Use --comment-file <path> to write a PR comment body, or
--github-step-summary inside GitHub Actions to append the review to
GITHUB_STEP_SUMMARY.
A copyable GitHub Actions workflow is available at
examples/github-actions/bluewright-pr-review.yml. It runs bluewright pr,
uploads the generated ERD artifacts, appends the Markdown review to the step
summary, and upserts a sticky PR comment.
The Bluewright project CI runs the Node suite plus a Chromium browser E2E check for the generated diff HTML report.
This repository also runs .github/workflows/bluewright-erd-review.yml on pull
requests, using the local checkout to review ERD changes and publish the review
summary as a sticky PR comment.
Supported extractors:
- Prisma
schema.prisma - SQL
CREATE TABLE, inlineREFERENCES, table-levelFOREIGN KEY, andALTER TABLE ... ADD FOREIGN KEY - GORM model structs registered through
AutoMigrate, plus explicitTableName()models - Drizzle
pgTable,mysqlTable, andsqliteTable - TypeORM
@Entity,@Column,@ManyToOne, and@JoinColumn - Sequelize
sequelize.defineandModel.init - Django
models.Model - SQLAlchemy declarative models
- Rails migrations and schema files with
create_table/ foreign keys
Supported agents:
claude -pcodex exec
Agent output is treated as audit/enrichment data. Deterministic extractors stay the source of high-confidence schema facts.
Apache-2.0