Laravel Cartographer Laravel Package

Product Decisions This Supports

• Making domain boundaries visible and reviewable. Named groups let a team declare the subsets it actually talks about (billing, identity, catalog) and get docs/erd/billing.md committed beside the main docs/erd.md. That turns "we think Billing is loosely coupled" from a whiteboard opinion into a reviewed artifact. Use it to support module-extraction, service-boundary, and team-ownership decisions, and to show the cross-group edges that would become integration contracts if you ever split.
• Gating architecture drift in CI, not in review comments. cartographer:check regenerates per config, exits 1 on drift, lists each stale file with a short diff, and writes nothing — safe on a read-only checkout. This is a policy decision a PM can actually own: "diagrams are code; stale diagrams fail the build." Cheap to adopt, hard to argue with, and it removes the recurring "please update the ERD" review nit.
• Scoping and sequencing architecture work. --only/--except allow one-off focused runs without touching committed group files, which supports ad-hoc analysis during incident reviews, pre-refactor audits, or a single team's spike without churning the repo.
• Build vs buy for diagramming. Replaces hand-maintained Mermaid/dbdiagram/Navicat artifacts and paid collaborative diagram tools for the "what does our schema look like today" job. The diagram is derived from the models themselves, so it cannot silently rot — the failure mode of every manual diagram. Keep paid tools if you need interactive exploration, data lineage across non-Eloquent stores, or a hosted catalog for non-engineers.
• Onboarding and documentation spend. Auto-generated, themed images (--format=svg/png) give you embeddable visuals for onboarding docs, RFCs, and architecture wikis without a designer or a screenshot-refresh ritual. Themes are image-only, so committed Markdown stays theme-neutral and diffs stay readable — a real decision input when deciding whether to commit diagrams at all.
• Roadmap and tech-debt signals. Renderer limit warnings (50k chars / 500 edges) fire on the run that caused them without failing anything — a free, early indicator that a domain has grown past what a human (or a hosted renderer) can read. That is a legitimate input to "when do we split this module" conversations, and it costs nothing to listen to.
• Extensibility without a fork. The public DiagramGenerator pipeline (used by every command) plus public export/theming/limit APIs mean custom docs generation — e.g. per-team pages, a docs site build step — is a small integration task rather than a maintained patch. Lowers the cost of saying yes.
• Performance makes CI adoption realistic. Per-model cached relationship detection means drawing a model into the full diagram and into its groups costs one pass; multi-diagram runs stay fast enough to sit in a pull-request job rather than a nightly one.

When to Consider This Package

Consider it when most of these hold:

• The app is Laravel 12 or 13 on PHP 8.3+. This is the hard gate — Composer will hold you on an earlier release rather than break the project, so on Laravel 11 or PHP 8.2 you get nothing until you upgrade.
• Eloquent models are the source of truth for schema relationships, and you want diagrams that follow the code rather than a DBA's snapshot.
• You have more than one domain or team and a recurring argument about coupling, ownership, or extraction — the named-groups feature is the reason to adopt now rather than the base diagram feature alone.
• You want a CI-enforced documentation invariant and have a checkout that can run artisan in a read-only fashion.
• You are willing to accept a dev-only toolchain: symfony/process is pulled in, and PNG/SVG export needs a separately installed mermaid-cli (node) on the machines that export. Note the deliberate design win: cartographer:check compares the Mermaid source written beside the image, so CI validates exported diagrams without installing node — you can keep node out of CI entirely.

Look elsewhere when:

• The stack is not Laravel/Eloquent, or the schema is largely not expressed in Eloquent relationships (raw SQL, legacy tables, cross-service stores) — the diagrams will be materially incomplete and therefore misleading.
• You need an interactive, queryable data catalog or column-level lineage, or a hosted surface for non-engineers to browse. This produces files, not a product.
• You need runtime schema introspection, migrations-from-diagrams, or DB-diffing — out of scope; it reads models and writes Markdown/images.
• Your CI is hermetic and cannot run artisan, or the repo must stay dependency-minimal (the symfony/process addition and PHP 8.3 floor are real costs).
• Your team will not review committed diagram diffs. A drift gate on files nobody reads is pure friction; fix the review habit or skip the gate.

How to Pitch It (Stakeholders)

To executives: This is low-cost developer tooling with no production footprint and no runtime dependency — it reads our existing models and writes Markdown (and optionally images) into the repo. It converts architecture documentation from a manual chore that decays into a build artifact that fails CI when it drifts. The payoff is faster onboarding, fewer "how does Billing touch this?" conversations, and an evidence-based trigger for module-splitting decisions, at the cost of a few days of setup. Principal risks are the PHP 8.3 / Laravel 12–13 floor (confirm we are already there before committing) and that the value depends on the team actually reading the diffs.

To engineering: Adopt for the CI drift gate and per-domain groups. cartographer:check is read-only, compares the committed Mermaid source (so CI needs no node, even for exported images), and lists each stale file with a diff. Export, theming, and limit checks are public alongside a DiagramGenerator every command already runs through, so custom docs pipelines are a small integration, not a fork. Relationship detection is cached per model, so full-plus-group runs cost one pass. Cost of entry: symfony/process as a dev dependency and mermaid-cli installed only where images are produced. Start with two groups in a single PR job, measure whether stale-diagram failures are being fixed or muted, then expand.