Laravel Cartographer Laravel Package

Technical Evaluation

• Architecture fit: laravel-cartographer is a Laravel-native documentation/architecture tool: config-driven diagram generation, Artisan commands, committed Markdown outputs, and an internal DiagramGenerator pipeline. For a TPM, the main value is turning Laravel model relationships into reviewable ERDs and domain-level diagrams that live in the repo and can be gated in CI. Named groups map well to modular-monolith or bounded-context discussions, letting teams commit a main ERD plus per-domain diagrams such as docs/erd/billing.md.
• Integration feasibility: Feasible for Laravel 12/13 projects on PHP 8.3+. Core generation and cartographer:check are straightforward CI additions. Image export is optional and depends on an externally installed mermaid-cli plus symfony/process; it is not a package dependency. The read-only-safe check command is a good fit for PR pipelines. Composer’s constraint behavior reduces accidental upgrade risk for projects that do not meet requirements.
• Technical risk: Moderate but bounded. The main risks are environment drift around optional mermaid-cli, CI runtime growth as configured diagrams/groups expand, and misinterpretation of what cartographer:check validates: it compares committed Mermaid source, not the rendered image. Renderer-limit warnings at 50,000 characters or 500 edges are advisory only and will not fail CI, so large diagrams may still break hosted renderers. Themes apply only to images, which is good for keeping committed Markdown neutral. No breaking changes are called out for v1.2.0, but the PHP 8.3/Laravel 12–13 floor is the primary adoption gate.
• Key questions: Which active projects meet PHP 8.3 and Laravel 12/13? Is docs-as-code already accepted for architecture artifacts? Which domains should become committed groups, and who owns each file? Will image export be required in CI, or is source-level drift checking sufficient? What CI runtime budget exists for full regeneration? Are any current ERDs large enough to trip renderer warnings? Do we need custom reporting through DiagramGenerator? Is the package’s maintenance cadence and documentation sufficient for production dependency policy?

Integration Approach

• Stack fit: Strong fit for Laravel 12/13 teams using Artisan, config files, and CI-based documentation checks. The package can remain a development/documentation dependency. Optional image export fits a separate docs job or release workflow rather than every application runtime. The public generation pipeline gives TPMs and platform teams a path to automate architecture artifacts without shelling out to commands.
• Migration path: Treat this as an additive docs/CI capability. Install the package, publish/define the diagram config, establish a baseline main ERD, then introduce named groups by domain. Commit generated Markdown, add cartographer:check to PR CI on a read-only checkout, and only then add optional image export where stakeholder-facing diagrams are needed. If existing ERD tooling exists, run this in parallel for one domain before replacing anything.
• Compatibility: PHP 8.3+ and Laravel 12/13 are required. symfony/process ^7.2 || ^8.0 is needed for image export, and mermaid-cli must be installed separately. CI that only runs cartographer:check does not need Node. Composer will hold projects on an earlier release rather than break incompatible environments. Themes/fonts affect images only; committed Markdown remains theme-neutral, which supports broad compatibility.
• Sequencing: 1) Confirm PHP/Laravel versions across target repos. 2) Install and configure the package. 3) Define domain-aligned groups. 4) Generate and commit baseline diagrams. 5) Add cartographer:check to PR CI. 6) Add optional image export job with pinned mermaid-cli if images are required. 7) Apply themes/fonts only in the image job. 8) Monitor renderer-limit warnings and split large groups as needed. 9) Integrate DiagramGenerator into custom reporting or docs pipelines if manual commands become insufficient.

Operational Impact

• Maintenance: Committed diagrams become maintained artifacts. cartographer:check reduces drift by failing CI and listing stale files with a short diff, but teams must regenerate and commit updates. Named groups multiply files, so ownership should be explicit. Image export adds external tool maintenance: mermaid-cli, Node in the image job, and renderer version pinning. Source-level checks remain Node-free, which keeps the primary CI gate lightweight.
• Support: Documentation is available, and the public generation pipeline plus command-level scoping (--only, --except) reduce bespoke scripting. Support burden is mostly process-related: teaching teams to treat diagrams as code, keeping group definitions current, and interpreting check failures. A platform or architecture owner should own CI wiring and group taxonomy.
• Scaling: Per-model relationship detection caching improves multi-diagram runs, especially when the same model appears in the full ERD and multiple groups. Scaling is limited more by diagram size and CI duration than by package internals. Renderer warnings at 50,000 characters/500 edges are an early signal to split domains. Full cartographer:check regenerates everything config declares, so large portfolios should expect longer CI jobs and may need scoped checks or scheduled full checks.
• Failure modes: Stale committed Markdown causes cartographer:check to exit 1 with a diff. Missing mermaid-cli fails image export but does not block source-level checking. Renderer limits produce warnings without changing exit codes, so a diagram can pass CI yet fail in a hosted renderer. A relation leaving a group is drawn as an empty box, which is useful but can confuse readers if group boundaries are poorly chosen. The check validates Mermaid source, not rendered image freshness, so image-only staleness is not caught. Composer constraints may block upgrades on older PHP/Laravel stacks.
• Ramp-up: Low for Laravel teams already using Artisan and CI. Medium for domain grouping and architecture ownership, because group boundaries encode team semantics. Optional image export adds a small Node/mermaid-cli learning curve. A sensible TPM rollout is one bounded context first, then expand groups and CI enforcement once the regeneration workflow is proven.