Onboarding Laravel Package

Technical Evaluation

Architecture fit GuavaCZ/onboarding is a Laravel package that layers an onboarding domain (steps, progress/state tracking) onto an application, with first-class Filament integration — evidenced by the 2.2.1 fix targeting "filament v5." It follows the standard Laravel package shape: service provider registration, publishable config and migrations, and Filament panel plugin/resource registration. For teams already running Filament for back-office/admin surfaces, this fits the existing architecture with minimal new surface area. For teams not on Filament, the package is likely a partial fit at best — the core onboarding models may be usable headless, but the value proposition (admin UI for managing onboarding flows) is Filament-bound.

Integration feasibility High. The conventional composer require → publish config/migrations → register plugin in the panel provider path applies. The release itself is a patch (2.2.1) containing a single bug fix plus a styling commit, indicating a semantic-release / release-please pipeline with conventional commits. Integration effort is dominated by data modeling decisions (how onboarding state maps to your user/tenant model) rather than by the package's wiring.

Technical risk

• Framework coupling (primary risk). A patch release whose sole functional change is "filament v5" compatibility implies 2.2.0 broke against Filament v5. That is a tight coupling signal: the package tracks Filament internals closely enough that upstream releases can break it, and fixes arrive only when someone reports them. Confirm whether the composer constraint permits Filament v4 and v5 simultaneously or forces an upgrade.
• Single-maintainer / small-team exposure. GuavaCZ is a small vendor namespace; bus-factor and response latency on Filament breakage are real.
• Schema ownership. Published migrations become yours. Onboarding state tables are user-facing and stateful; rollback and backfill strategy must be designed before first deploy.
• Low direct risk from this release. 2.2.1 introduces no API changes, no deprecations, no config changes. Regression surface is limited to the Filament v5 code path.

Key questions

1. What precisely was broken in 2.2.0 under Filament v5, and does 2.2.1 also support Filament v3/v4, or is this a v5-only branch?
2. Is Filament v5 GA/stable, and what is the package's declared support matrix (Laravel versions, PHP versions, Filament majors)?
3. Does the package offer a headless mode — usable models/services without Filament — or is the admin panel mandatory?
4. What are the migration contents, and are they additive-only (safe) or do they alter existing tables?
5. Is onboarding progress modeled as an explicit state machine with idempotent transitions, or as ad-hoc boolean/JSON flags?
6. Test coverage and CI maturity: does the repo run a matrix across supported Laravel/Filament versions?

Integration Approach

Stack fit Target stack is Laravel (10/11/12 class) + PHP 8.2+ + Filament. The release cadence and commit hygiene suggest a maintained, modern package rather than an abandoned one. Fit is strong where Filament is already the admin layer; weak where the product uses Nova, Livewire-only, Inertia/Vue, or a separate SPA admin.

Migration path 2.2.0 → 2.2.1 is a drop-in patch. Two cases:

• Already on 2.2.0 and broken against Filament v5 — upgrade immediately; this is the fix.
• On an older 2.x with Filament v3/v4 — do not upgrade reflexively. Verify the composer constraint still resolves against your pinned Filament major before bumping; a "v5 fix" patch can carry a widened-or-narrowed constraint that silently changes your dependency graph.

Compatibility Build an explicit support matrix before adoption: package version × Laravel × PHP × Filament major. Treat Filament as the binding constraint. Pin the package to a minor (^2.2) and let patch releases flow, but gate minor bumps behind a staging run.

Sequencing

1. Spike in a throwaway branch: install, publish config/migrations, register the panel plugin, confirm the admin UI renders.
2. Model the onboarding state against a real entity (user or tenant) and validate the progress-tracking semantics — this is where rework happens, not in the install.
3. Run migrations in staging against a production-shaped dataset; verify rollback.
4. Write integration tests around onboarding transitions so upstream Filament breakage surfaces in your CI, not your users' sessions.
5. Roll to production behind a feature flag; adopt broadly only after one clean Filament upgrade cycle.

Operational Impact

Maintenance Low ongoing effort in steady state; the cost is concentrated in Filament upgrade windows. Automated changelog/release tooling is a positive maturity signal. Budget a recurring task each time Filament ships a major: verify the package, upgrade in lockstep, or pin and defer. Because the package is small, expect to read its source when behavior is ambiguous — documentation depth is unverified.

Support GitHub-issues-based support with no commercial SLA implied. Acceptable for internal admin tooling; a concern if onboarding is a customer-facing, revenue-adjacent flow. Establish an internal fork-or-patch fallback plan in case Filament breakage goes unaddressed.

Scaling Onboarding progress is per-entity state — row volume scales with user count, not traffic. Watch for per-step queries or N+1 patterns when rendering progress across lists; index the foreign key on the progress table. If progress is read on every page load to gate features, cache it and invalidate on transition. Migration size matters more than query volume: onboarding tables grow monotonically with users.

Failure modes

• Filament major upgrade breaks the panel registration or resource rendering (observed pattern: this is exactly what 2.2.1 fixes for v5).
• Migration conflicts if you already own tables with similar names — resolve before publish.
• Inconsistent onboarding state from non-idempotent step completion (double-submits, retries, queued jobs).
• Silent dependency-constraint drift on composer update.
• Abandonment: no upstream fix for a future Filament release, forcing an internal fork.

Ramp-up A Laravel developer is productive in under a day on the domain model; the real ramp is Filament conventions (panel providers, resources, actions) — budget a few days for developers new to Filament. TPM-level cost is a half-day dependency and support-matrix review. Recommended posture: adopt for internal/admin onboarding flows with a pinned minor and a tested upgrade cadence; hold for customer-facing critical paths until the Filament-support matrix and the maintainer's responsiveness across one full upgrade cycle are confirmed.