Db Draw Laravel Package

Product Decisions This Supports

• Documentation as a build artifact: Enables a decision to treat the ER diagram as generated output rather than a hand-maintained Confluence page — it can be regenerated from the live schema on every migration, eliminating a recurring "stale docs" chore from the backlog.
• Build vs. buy for schema visualization: Replaces paid ER-diagram SaaS seats (dbdiagram, Lucid, ER/Studio) with a zero-cost, MIT-licensed, self-hosted generator for teams whose diagrams are read far more often than edited.
• Onboarding and developer-experience roadmap: Supports investment in "time-to-first-PR" metrics by giving new engineers and contractors a readable, always-current map of a 50–200 table schema without database access or tribal knowledge.
• Schema-change governance: Makes schema drift visible in pull requests — a diagram diff alongside a migration is a cheap review aid for architecture and data-model decisions (new junctions, denormalization, orphan tables).
• Legacy modernization and migration planning: Useful input for decisions about decomposing a monolith, planning a module boundary, or scoping a data migration — a generated diagram is faster to produce and less political than a hand-drawn one.
• Scope triage for internal tooling: Because it is a Composer library rather than a product, the decision it supports is usually "adopt as a CLI/docs step" — not "build a schema-visualization product," which would be a much larger commitment.
• Documentation format standardization: Forces a decision on the canonical diagram dialect (PlantUML, Mermaid, Graphviz, etc.) and where it lives — repo-committed source vs. generated HTML in a docs site — which downstream teams then inherit.

When to Consider This Package

Consider it when:

• The stack is PHP/Laravel (or any Composer-managed PHP app) and the database is relational (MySQL, PostgreSQL, MariaDB, SQL Server).
• The schema is large enough that SHOW TABLES is no longer explanatory — roughly 20+ tables, or anything with meaningful FK relationships.
• Documentation is currently manual, outdated, or nonexistent, and nobody owns it.
• You want diagrams produced in CI or a make docs/Artisan-style command with no external service, no credentials leaving the network, and no per-seat cost.
• Your team already reads diagrams as text/code (PlantUML, Mermaid) and prefers reviewable, diffable artifacts in version control over binary or hosted canvases.
• The blast radius of failure is low: this is documentation, not a runtime dependency on the request path.

Look elsewhere when:

• You need interactive, collaborative, or drag-to-edit diagramming — this is a generator, not an editor. Pair it with a hosted tool or accept read-only output.
• You need guaranteed vendor support, an SLA, security review artifacts, or a long-term maintenance commitment. At ~22 stars the project has a small maintainer base and a real bus-factor risk.
• The data store is non-relational (document, graph, wide-column) or the schema is defined primarily in code without DB-level FK constraints — the output quality degrades sharply.
• Your engineering org is not PHP-based; shelling out to a PHP binary from a Node/Go/JVM pipeline adds a runtime you otherwise don't need.
• You require rich data-dictionary output (column comments, PII classification, lineage, ownership). A generator shows structure; governance metadata usually needs a catalog tool.
• Diagrams must be produced in real time inside an application UI — this is a build-time/CLI concern, not an embedded rendering library.
• Your security posture forbids a library with a thin dependency/maintenance trail, or you cannot pin and vendor it internally.

Adoption criteria to apply: pin the version, review the transitive dependency tree (DB introspection typically pulls in a DBAL), confirm the supported output formats match your docs pipeline, and verify it runs against a schema-only dump — never point it at production credentials.

How to Pitch It (Stakeholders)

For executives: This is a small, MIT-licensed, zero-cost PHP library that turns our existing database schema into an up-to-date ER diagram automatically. It removes a manual documentation task, shortens onboarding for new engineers and contractors, and makes schema changes reviewable in code. Cost is effectively one engineer-day to wire into the pipeline; the only risk is that it is a small open-source project with limited maintainers, which we mitigate by pinning the version and treating the diagrams as regenerable artifacts rather than a critical system.

For engineering leads: Low-commitment, high-leverage addition to the docs toolchain. It introspects the schema and emits a diagram in a text-based format we can commit, diff, and review — so the diagram stops rotting the moment the first migration lands. It fits naturally into a Composer/Laravel repo and a CI job, has no runtime footprint, and imposes no architectural constraint. The trade-off is explicit: we get automation and freshness, but not an editor, not a data catalog, and not a vendor with a support contract. Recommended as an opt-in docs step with a pinned version, evaluated on one representative service before wider rollout.

For the team asking "why not just use dbdiagram/Lucid?": Those are good tools for designing a schema collaboratively. This solves a different problem — keeping the already-shipped schema documented without anyone remembering to update a canvas. Use both if you like: hosted tool for design conversations, generated diagram for the living reference.

Decision requested: approve a one-day spike to wire it into the docs pipeline for one service, with a go/no-go based on output quality on our largest schema and the dependency footprint.