Filament Onboarding Laravel Package

Technical Evaluation

Architecture fit. Unchanged in substance: a Filament panel plugin delivered as a standard Laravel package (service provider, config, publishable migrations, views/assets). Journeys, steps and per-user progress are database-backed, while completion logic is delegated to host-registered conditions — the right seam for a TPM, since product owns journey content and ordering and engineering owns only the predicates. The notable addition in this release is that the destination picker now lists a panel's ->tenantProfile() page, not just ->pages(), so a multi-tenant onboarding can finally route "finish setting up your team" to the tenant profile. That narrows one of the gaps flagged in the previous assessment, though it addresses destinations, not progress scoping.

Integration feasibility. Low-friction, but the version story has changed materially and for the better. The previous assessment described this as a v5-only package. It is now two maintained lines sharing one source: 1.x on Filament v4 (this release, the backport of v2.6.0) and 2.x on Filament v5 (upstream). Consequences for us: (a) a greenfield Filament v5 panel sits on the 2.x line, which is the upstream where fixes originate — good; (b) v4 panels now have a supported path rather than being stranded; (c) Filament v3 remains out of scope; (d) we must be explicit that 1.x is a manual backport line, not the stable branch — Dependabot only targets the default branch, so 1.x toolchain and dependency updates arrive by hand, as they did here. Pinning must record which line, not just a version.

Technical risk.

• Maturity/adoption: still small, still a single-maintainer project, but the signal improved. Four outside contributors shipped fixes in this release, and the work was driven by measuring the package against a real CMS panel with nested form resources — that is production usage, not a demo. Bus factor remains the dominant risk; it is now visibly mitigated rather than merely hoped for.
• Per-request footprint: the release exposes that definitions are memoised per request and that the memo previously leaked across requests under Octane and queue:work, serving stale flows until a worker recycled. Fixed, but it confirms the caching model is subtle and that long-lived-worker deployments carry a distinct risk class. Condition-evaluation cost per page view still needs our own measurement.
• Resolved selector fragility: nested state paths (form.details.title vs the bare name title) previously broke every stop on a Group/Section/Tab/wizard-nested form, and the picker returned no targets at all on 8 of 34 form resources that reached for the Livewire component. Both fixed. This was the single largest "will tours actually work on our forms" risk and it is now substantially retired — but it also demonstrates how fragile the selector layer is and how easily the failure is silent.
• Fail-closed behaviour persists: a stalled tour writes its stall to localStorage, so a broken selector returns stalled on every reload until the subject presses Skip. The specific cause is fixed; the design pattern is that tour failures are sticky and user-visible. Demand a fail-open/dismiss path.
• Client-side performance: the watcher previously restarted a three-second search every frame (sixty renders/second, each with its own poller) whenever a target was hidden behind another tab. Fixed. Worth knowing it existed.
• Upgrade mechanics: no breaking changes and no new migrations, but the tour runner changed and requires php artisan filament:assets. A skipped asset rebuild yields a stale runner — a visible, confusing failure in an otherwise no-op upgrade.
• Content-as-data, translations, accessibility, multi-tenancy: unchanged open questions. Journey versioning/rollback is still unaddressed. Tenant progress keying is still unanswered — the release fixes tenant-profile navigation, which is not the same thing.
• Dual-line drift: a shared source with divergent Composer constraints and Livewire internals means bug fixes and toolchain updates flow to 1.x only by deliberate backport. Ask what the backport SLA is and whether 1.x receives security-relevant dependency updates.

Key questions.

1. Which line are we on, and what is the backport SLA from 2.x to 1.x — including dependency and toolchain updates that Dependabot cannot reach?
2. How is progress keyed for multi-tenant panels (user, panel, tenant, journey version), and are journeys themselves panel/tenant-scoped?
3. Has the Octane/queue-worker memo fix been verified under our deployment topology, including any custom cache or worker configuration?
4. How and when are conditions evaluated per request, and is progress cached with correct invalidation on condition-relevant events?
5. What happens when a condition throws — fail-open or fail-closed — and can a stalled tour be cleared without user action?
6. Is journey content versioned, and can we edit or roll back a live journey without corrupting in-flight progress?
7. Will the asset rebuild (filament:assets) be automated in our deploy pipeline, and is there a smoke test that catches a stale tour runner?
8. What is the test coverage and CI signal, and who is the maintainer's backup?
9. Are tours accessible — keyboard dismissal, focus trapping, reduced motion, RTL — and do translations cover journey copy, tour copy, and UI strings with a defined fallback?

Integration Approach

Stack fit. Unchanged: Laravel on a current PHP 8.x runtime, Filament, Livewire, and the existing panel — no separate admin surface, no new identity concept. Reuses the existing User model and panel middleware. Multi-tenant panels should now expect the tenant profile to be reachable as a journey destination; validate tenancy and progress scoping before authoring.

Migration path. Still no incumbent worth displacing in most cases — the alternative is scattered, untracked welcome modals. Where such code exists, inventory it, map each step to a condition or page-reach trigger, run in parallel on staging, then delete the old widgets. Content migration remains a product task with a content-freeze window, not a code freeze. New this release: the target picker now works on nested forms and forms that introspect the rendering component, so re-audit any form resources previously written off as "can't be toured" — on the upstream panel that was roughly a quarter of them.

Compatibility. Pin the package and record the line (1.x for Filament v4, 2.x for v5); do not float. Treat the asset rebuild as part of the upgrade, not an optional step: the tour runner changed in this release and a stale runner is silently wrong. Verify published assets survive filament:assets and production builds, test against our custom theme, and confirm locale resolution per request. Add a smoke test that boots the panel and renders a page with an active journey — it catches both Filament-upgrade markup changes and stale-asset regressions.

Sequencing.

1. Spike (1–2 days): install on a scratch panel on the correct line, publish migrations, author one journey across a nested form (tabs or wizard), confirm per-page behaviour and query count.
2. Instrument conditions: 3–5 predicates in a small registry with unit tests; idempotent and exception-safe.
3. Pilot: one real journey for one cohort, analytics on step completion, tour dismissal, and stall events.
4. Harden: caching with correct invalidation under our worker model, fail-open handling, accessibility pass, pilot translations.
5. Generalize: enable globally, then add spotlight tours once selector stability is proven on our own forms.
6. Handover: authoring conventions, content QA checklist, and an upgrade runbook that names php artisan filament:assets and the smoke test.

Operational Impact

Maintenance. Our surface is conditions, content, and translations; the vendor surface is now two lines with a manual backport between them. Budget a few hours per Filament minor upgrade for regression testing, plus asset republish. Vendor risk is lower than the prior assessment implied — external contributors, a real production reference implementation, and a maintainer actively fixing Octane-correctness bugs — but it is still a small project. Keep the version pinned, keep an internal-fork readiness check (MIT permits it), and name an owner who watches releases and knows which line we track.

Support. Two channels, as before: engineering for conditions and rendering, product/ops for authoring. The authoring channel gains a specific runbook item — if a tour stalls, the subject is stuck until Skip, and the stall survives reloads. Give support a documented escape hatch and a way to preview a journey as a specific user. Localization still adds a translation workflow with a fallback policy.

Scaling. Server-side: the checklist-on-every-page pattern remains the scaling question; per-request condition evaluation and progress lookups multiply across page views. Expect request-level memoisation or a short-TTL per-user cache, with cheap indexed conditions. Progress rows grow users × journeys — trivial in size, but they need a cleanup policy for deleted users and retired journeys. Client-side: meaningfully better after this release — the per-frame render/poller storm while waiting on a hidden target is gone, and horizontal-scroll targets (every table on a phone) now resolve — but tour JS still scales with the browser, not the server.

Failure modes.

• Broken or nested-state-path selector → tour parks, Next disabled, stall persisted in localStorage until Skip. Specific causes fixed; the sticky failure mode is by design.
• Stale published assets after a runner change → old tour runner behaviour, silently; now the expected failure if filament:assets is skipped.
• Long-lived worker serving stale definitions → authors disable a flow, users keep seeing it; fixed for Octane and queue:work, but verify on our topology.
• Condition exception → step never completes or panel error; require try/catch and fail-open.
• Filament minor upgrade changing markup → stuck or mispositioned spotlight; detect via dismissal-rate and stall-rate anomalies.
• Migration not run → hard failure on panel boot; keep in the deploy checklist.
• Missing translation → untranslated or blank step; enforce fallback locale.
• Orphaned progress on user deletion → data hygiene, not user-facing.

Ramp-up. Engineering ramp-up stays low — roughly half a day to a day for a Laravel/Filament developer to install, author a journey, and register a condition. This release adds a short but non-zero upgrade-runbook step (asset rebuild plus smoke test) that should be scripted once and forgotten. Product ramp-up remains the larger investment: an authoring walkthrough, a copy/translation style guide, and a documented definition of "done" per step. Time to production pilot is still plausibly one to two weeks, with the remaining uncertainty concentrated in multi-tenant progress keying, per-request performance under our load, and the backport policy for whichever line we adopt rather than in the integration itself.