Laravel Truss Laravel Package

Product Decisions This Supports

• Build vs. buy for schema documentation. Truss turns "keep the ERD up to date" from a recurring manual chore (dbdiagram, Lucid, a wiki page nobody trusts) into a generated artifact read from the live schema. The decision it unlocks is whether to staff or license a diagramming workflow at all — the honest answer for most Laravel teams is no.
• Prioritising structural debt on the roadmap. truss:doctor produces deterministic, stable-coded findings (TRUSS-IDX-001, missing primary keys, unindexed foreign keys, duplicate indexes, money-as-float). That converts "our schema is a mess" into a sized, enumerable backlog you can scope into a hardening sprint and re-measure afterwards.
• Definition of done for migrations. truss:export --check fails the build when the committed schema artifact drifts. That is a policy decision, not a technical one: do schema changes require a refreshed committed docs/schema.dbml? Truss makes the policy cheap to enforce.
• AI tooling investment. --format=llm, --compact, --focus, annotations, and the optional read-only MCP server give coding agents real structure as grounding context. The product decision is whether to standardise schema-context injection across agent workflows (one pipeline, one source of truth) rather than letting each engineer paste ad-hoc DDL into a prompt.
• Architecture and platform boundaries. The multi-connection picker makes module databases and cross-module foreign keys visible in one view — useful evidence when arguing about modular monolith boundaries, service extraction, or enforcing isolation.
• Data dictionary as a deliverable. Markdown/DBML/JSON/CSV exports serve audit, compliance, vendor integration, and analytics onboarding. Because it is structure-only, the privacy review is short and the artifact can be committed and shared.
• Support and onboarding cost. A gated /truss on staging lets support engineers and new hires answer "how do these tables connect" without a DB client, prod credentials, or a senior engineer's time — a direct lever on time-to-first-PR and ticket triage latency.
• Where the viewer lives. Choosing local-dev-only (--dev) versus gated staging/production is a real decision with an install-type consequence: dev dependencies never reach composer install --no-dev builds, so /truss 404s in production by construction.

When to Consider This Package

Adopt when most of these hold:

• The stack is Laravel 12+ / PHP 8.2+ and the schema is relational (MySQL, Postgres, SQLite, SQL Server via Laravel connections).
• The schema is past the size where it fits in one head — roughly 20+ tables, or a team beyond 3–4 engineers.
• Diagrams today are hand-maintained and stale, or nobody has one.
• You are rolling out coding agents and want deterministic schema grounding without building a context pipeline.
• You want lightweight schema linting in CI and do not want to buy a data catalog or schema-observability SaaS.
• You can accept a read-only, single-tenant, config-driven viewer with authorization via a viewTruss gate.

Look elsewhere when:

• Non-Laravel, non-relational, or warehouse-centric. No MongoDB, no dbt lineage, no cross-system column-level lineage, no warehouse/semantic-layer modelling.
• You need collaboration. No comments, no ownership assignment, no proposed-change review on the diagram — it reads, it does not host discussion.
• You need data, not structure. No PII discovery, no row counts, no data profiling, no sampling. That is deliberate; do not try to bend it.
• You need runtime-dynamic connections. Connections come from config/database.php; hundreds of per-tenant databases are not the target shape.
• You need migration history or point-in-time schema versions. Diff is against the last cached snapshot, not an arbitrary revision.
• Procurement or enterprise support is mandatory. Single maintainer, MIT, 288 stars, zero dependents — no vendor to escalate to.

How to Pitch It (Stakeholders)

For executives — one paragraph. Truss is a free, MIT-licensed Laravel package that renders our live database structure as an interactive diagram inside the app, and exports that structure in standard formats. It replaces manual diagram upkeep and gives us three things we currently pay for in engineer hours: faster onboarding and support triage, a measurable schema-health backlog, and a CI check that stops undocumented schema drift. It also gives our AI coding tools accurate, current schema context, which reduces hallucinated columns and the review cycles they cause. No SaaS contract, no data leaves our infrastructure, no row data is ever read.

For engineering — the short version. composer require albertoarena/laravel-truss --dev, visit /truss. Auto-discovered, nothing to publish, local-environment-only by default. Mermaid and fonts are vendored, so it works offline and under a strict CSP. The snapshot is cached and rebuilt after migrations. Beyond the diagram: truss:doctor for structural linting with exit codes and presets suitable for CI, truss:export for deterministic DBML/JSON/CSV/Markdown/Mermaid/LLM output with a --check drift gate, and a Truss facade with an immutable builder if we want the same output programmatically. Command, facade, and dashboard share one pipeline, so the bytes match.

Risk read to state plainly. Early-stage, single-maintainer package with a small community and no downstream dependents — real bus-factor exposure. Mitigations are structural: MIT license, self-contained with no network calls, dev-dependency by default, and it only touches schema metadata. Exit cost is a composer remove and deleting a config file. Recommend a scoped pilot (one repo, local + gated staging) with the doctor rules wired into CI as a non-blocking warning first; promote to blocking once the existing findings are triaged.