Filament Clusters Laravel Package

Technical Evaluation

Architecture fit. The package is a narrow, single-purpose addition to Filament's admin layer: it groups related resources and custom pages under a shared URL prefix, navigation section, and breadcrumb trail. That places it in the presentation/routing tier, not the domain or data tier. Blast radius is therefore theoretically contained — no migrations, no publishable service provider, no asset build — which is the strongest argument for the architecture fit. It maps cleanly to a domain-per-cluster information architecture (Billing, Catalog, Support, Settings), so IA becomes a namespacing change rather than a refactor. The disqualifying caveat is that Filament is already absorbing similar clustering into core; adopting this package is a bet that the convenience today outweighs a likely exit later.

Integration feasibility. Low technical effort, moderate organisational effort. Installation is composer require guava/filament-clusters:^1.5 plus one static ($cluster) on each resource; resources then live under app/Filament/Clusters/{Domain}/Resources/. No database or config surface to manage. The real cost is not integration, it is reorganisation: moving a resource into a cluster rewrites its route name (filament.admin.resources.invoices.index becomes something like filament.admin.clusters.billing.resources.invoices.index). That ripples into hardcoded route() calls, seeded ACL/permission records, Gate definitions, tests, and any external deep links or bookmarks. Feasibility is therefore high for greenfield panels and conditional for existing ones — condition being a named owner for the URL-break migration PR.

Technical risk. Four items belong on the risk register, in order:

1. Metadata contradiction (highest diligence flag). The package description says it clusters "multiple fields into one visually," while the documentation describes navigation clustering. These are different features — form-field grouping versus sidebar/URL grouping. With zero dependents, nobody has validated the package against an outside use case. A one-day spike must resolve which it is before it influences any commitment or roadmap statement.
2. Compatibility claim unverified. Release 1.5.0 claims Laravel 12 support, shipped quickly — a good maintenance signal, but a single data point. Confirm composer.json actually widened laravel/framework and filament/filament constraints rather than only editing a CI matrix; a CI-only change is invisible in a changelog and fails at install time.
3. Cache behaviour. Any package leaning on Filament internals can behave differently once components are cached. php artisan route:cache failing under clustering is a hard stop, not a workaround.
4. Single maintainer, community support only, zero dependents, low score (0.3), no community traction signals. Acceptable for internal tooling; disqualifying for customer-facing, SLA-bearing, or revenue-critical panels.

Key questions for the spike. Which feature does the package actually implement? Does route:cache plus filament:optimize survive a clustered resource? Does the 1.5.0 release genuinely widen Composer constraints? Does Filament-native clustering already cover the need — and if so, is adopting this package a permanent two-convention tax for near-zero upside? What is the full route-name diff across the panel?

Integration Approach

Stack fit. Requires Laravel 11/12 with Filament v3. Fits when the admin panel has outgrown a flat resource list into several distinct functional domains and is expected to keep growing. Does not fit when the panel has a handful of resources with no realistic growth — the abstraction earns nothing and the URL churn costs something.

Migration path. Treat resource reorganisation as a URL-breaking change with its own release note, not a refactor chore. The migration sequence per cluster:

1. Capture a baseline: php artisan route:list --path=admin > routes-before.txt.
2. Pick one low-traffic domain (Settings or Support) as the pilot — two or three resources.
3. Build the cluster; assign resources via the $cluster static; set cluster-level $navigationSort so domain ordering is deliberate and resource sorting stays local to the domain.
4. Regenerate and diff: php artisan route:list --path=admin > routes-after.txt; diff routes-before.txt routes-after.txt. That diff is the day-one deliverable; everything that breaks later shows up in it.
5. Grep for the old route names across code, seeders, policies, and tests before merge.
6. Add one HTTP-level smoke test per cluster (/admin/billing/invoices), not merely a getUrl() assertion.
7. Run the caching passes: filament:optimize, route:cache, config:cache, optimize:clear.

Compatibility discipline. Keep every cluster definition thin — labels, icon, sort, URL prefix, nothing domain-specific. Put per-cluster behaviour (custom breadcrumbs, scoped labels) as overrides on your cluster subclass, never on the package's internals. This is what makes the eventual exit to Filament-native clustering a mechanical base-class change plus directory moves rather than an admin rewrite. Decide native-versus-package once, write it in the team's admin conventions doc, and do not run both conventions in one panel.

Sequencing. Land the Laravel 12 bump first as its own patch-level change (1.5.0 is compatibility-only and removes this package as an upgrade blocker). Land each cluster as a dedicated PR afterwards. Never bundle reorganisation with a framework upgrade — rollback must be a single revert.

Operational Impact

Maintenance. Low ongoing effort but non-zero ownership. Pin ^1.5, name an internal owner, and put a re-evaluation trigger on the calendar for the next Filament major. The upgrade plan should treat this package as a checkbox ("dependency compatible"), not a roadmap line.

Support. Community-only, single maintainer. The maintainer shipped Laravel 12 support within roughly a day of release, which is the strongest signal available — but it is one observation from a package with zero dependents and a low evaluation score. Escalation path for a defect is: wait for upstream, or fork, or migrate to native. The thin-convention discipline is what keeps that last option cheap.

Scaling. Scales fine horizontally — it is configuration, not runtime infrastructure. Scales acceptably in scope: adding the fifth screen to a domain costs one line rather than a routing decision, and that compounding saving is the actual payback. It does not scale into cluster-scoped authorization; the package provides no per-cluster permissions or ACLs. If cluster-scoped authorization was the reason you reached for it, you will write the glue anyway — and owning the small amount of routing yourself may be the better trade.

Failure modes to plan for. (a) 404 on a cluster route — debug in order: does the route exist at all, is $cluster set to the imported class rather than a string, does optimize:clear fix a stale component cache, is getSlug() overriding the prefixed path. (b) Broken deep links, bookmarks, and ACL seeds after a cluster move. (c) route:cache choking — hard stop. (d) Two competing conventions producing inconsistent navigation and two mental models for one sidebar. (e) Abandonment at the next Filament major, mitigated by the thin-convention exit.

Ramp-up. Low for engineers — the base cluster class and the "assigning resources" section of the README determine every other decision; a single pilot cluster on a branch is a one-to-two-day spike including verification. Ramp-up cost for PMs is mostly learning to frame cluster changes as URL-break releases with user-visible consequences, not internal refactors — because that is how they will be experienced by anyone with a saved link or a seeded permission.

Recommendation. Adopt as a convenience dependency with a scheduled exit review, contingent on the spike confirming the real feature set, the Composer constraint widening, and cache survivability. If any of those three fails, stop rather than work around it.