Mary Ui Starter Kit Laravel Package

Technical Evaluation

Architecture fit

mary-ui-starter-kit is a scaffold-grade Laravel 13 application template (Mary UI / Livewire / Tailwind), not a library you composer require into an existing app. v1.6.0 pushes it further in the direction of composed packages: the previously inline demo-mode logic is now delegated to lauroguedes/laravel-demo-mode, a package extracted from this kit and laravel-sso. That is a net positive for architecture — the demo surface (scheduled reset, rotating published password, login prefill, abuse throttling, floating notice bar) is now versioned, independently testable, and shared across two projects rather than reimplemented. The banner's shadow-root encapsulation and cron-derived countdown are the right calls: styling cannot leak into the host app, and the countdown cannot advertise a reset the scheduler will not perform.

The sandbox feature (DEMO_SANDBOX=scoped) is the more interesting architectural decision. Isolating only App\Models\User — while leaving roles and permissions shared — is a defensible scoping choice: the 53 seeded accounts are the demo's content, and forking RBAC would break the authorization story the kit exists to demonstrate. Marking the auth model itself, with seeded accounts carrying a null sandbox id so they remain common property, is deliberate and documented.

Integration feasibility

Low-to-moderate. Two integration shapes exist and should be chosen explicitly:

• Scaffold adoption — clone/generate a project from the kit. Straightforward; the risk is inherited dependency drift (below).
• Selective adoption — pull lauroguedes/laravel-demo-mode into an unrelated Laravel app. Feasible and clearly the package author's intent, but it is a brand-new, single-maintainer package with no independent adoption history; it needs a version pin and a vendored-fork contingency.

Technical risk

Key questions

1. Is lauroguedes/laravel-demo-mode pinned to an exact version or a caret range, and what is the fallback if it is abandoned?
2. Does the extraction preserve the previous DEMO_* env contract, or is this a breaking change for anyone templating the kit?
3. Is demo:doctor run in CI on main (and on PRs), or only available as a manual command?
4. Does the sandbox column ship with an index, and is there a migration path for existing deployments of the kit?
5. Is the sandbox trait's inertness (tests/Feature/DemoSandboxTest.php) tested against the default driver only, or across driver values?
6. Who consumes the demo surface — internal stakeholders, prospects, public traffic — and what abuse ceiling does that imply?

Integration Approach

Stack fit

Laravel 13 / PHP 8.x, Livewire + Mary UI (Tailwind/daisyUI). If the surrounding estate is Laravel 11 or 12, the kit does not drop in; only laravel-demo-mode itself is a candidate for selective adoption, and its Laravel constraint must be verified independently. If the estate is not Laravel at all, this release is not applicable — the demo-mode concepts (scheduled reset, published credential, scoped sandbox) transfer, the code does not.

Migration path

1. Freeze the current kit version as a reference build before upgrading.
2. Resolve Guzzle 8 across the dependency graph; treat any package still requiring ^7 as a blocker to be replaced or forked, not as a reason to pin the kit back.
3. Apply the new migration (nullable sandbox column), confirm it is additive and backfills to null — meaning existing rows stay "shared" and the demo stays functional immediately post-deploy.
4. Deploy with DEMO_SANDBOX unset. The trait, scope, and middleware are all inert in that state; this is the safe staging posture and should be the default in any non-demo environment.
5. Flip to scoped only on environments explicitly designated as demos.
6. Wire php artisan demo:doctor into CI with a non-zero-exit gate, plus a post-deploy smoke check.

Compatibility

The kit is a template, so "compatibility" means your divergences from the template, not third-party consumers. Any local customizations to the previously hand-rolled demo mode will conflict with the extraction — inventory them before merging, and expect to port them into the package's DEMO_BANNER_* env surface rather than patching the kit. The demo banner being env-dressed is helpful here: cosmetic and copy divergences become configuration, not code.

Sequencing

Dependencies first (Guzzle/math/MCP resolution and full test pass) → migration → inert deploy → demo:doctor green → scoped mode on a staging demo → two-session browser verification replicated → production demo. Do not enable scoped in the same change that bumps three transitive majors; if something breaks, you will not know which half caused it.

Operational Impact

Maintenance

The demo surface is now maintained in one place across two projects instead of two divergent hand-rolled implementations — a genuine reduction in long-term ownership cost, contingent on the package being actively kept. That contingency is the new operational dependency: this kit's demo capability now inherits the release cadence and bus factor of a single-maintainer package. Budget a quarterly check on that package's activity, and keep the ability to vendor it.

The three transitive majors (Guzzle 8, brick/math 1.0, laravel/mcp 1.0) are one-time costs paid now; they reduce future drift by aligning the kit with current major lines.

Support

demo:doctor is the most operationally valuable thing in this release. It converts a class of catastrophic misconfiguration — reset schedules that destroy data, published secrets in the wrong environment — into a pre-flight failure with a non-zero exit code. Treat it as a deployment gate, not a troubleshooting tool reached for after an incident.

Support burden shifts somewhat: a shared package means issues are triaged upstream, but also that a fix requires either waiting for a release or carrying a fork. Document the fork procedure before it is needed.

Scaling

The shared-account model scales fine for read-mostly demo traffic. scoped mode changes the write profile: every visitor adds rows to users on top of the 53 seeded accounts, and nothing prunes them until the scheduled reset. At sustained traffic, the Users list itself degrades (search over an ever-growing table) and the sandbox column becomes a hot filter — an index is not optional. The scheduled reset bounds the ceiling, so the practical question is: how many visitors arrive between resets, and is the reset interval short enough that the table never grows large?

Failure modes

• Reset does not run — cron misfires or the scheduler is not wired on the host. The banner's countdown derives from the same cron expression, so it will not promise a reset that is not coming, but it also will not detect that the scheduler is dead. Add an independent liveness check.
• Sandbox leak — most likely via a query-builder validation rule (the unique:users,email case) or a future controller that bypasses the scope. The existing pattern is documented; the audit obligation is ongoing.
• Demo package regression — silent behavioral shift on a minor bump. Pin it.
• Guzzle 8 conflict discovered late — surfaces as an unresolvable composer install after the kit has already been branched.
• Visitor confusion on logout — user expects a fresh state, receives the previous visitor's residue. The banner copy mitigates; nothing enforces.

Ramp-up

Low for a Laravel developer already fluent in Livewire and Mary UI: the demo mode is now an opaque dependency with a clean env surface, which is easier to learn than the hand-rolled version it replaced. The non-obvious concepts are the sandbox semantics — that the auth model is the scoped one, that seeded accounts are intentionally unscoped, that roles/permissions are shared by design, and that logout is not a reset. Those four facts belong in onboarding, because each one looks like a bug until it is explained. Budget half a day for a competent Laravel engineer, plus an hour of demo-mode-specific orientation covering demo:doctor, the DEMO_* variables, and the sandbox invariants.