Modules Laravel Package

Technical Evaluation

Architecture fit. This is a thin adapter, not a platform. It bridges two opinionated upstreams — nWidart/laravel-modules (modular monolith scaffolding: Modules/ tree, per-module service providers, modules_statuses.json, module:* artisan commands) and Filament's panel component discovery (discoverResources / discoverPages / discoverWidgets). The value proposition is narrow and real: without it, every module's Filament components must be hand-registered in a central PanelProvider, and that config file becomes an N-line merge-conflict hotspot as module count grows. With it, discovery is delegated to module conventions.

The fit is therefore conditional, not general. If we are not already committed to laravel-modules, this package asks us to adopt a modularization strategy and a bridge in the same breath — roughly 5–10x the scope of the problem it appears to solve. If we are already modular, it removes genuine boilerplate and is worth a spike.

Integration feasibility. Mechanically low-effort: one composer require, one provider/plugin registration, and Filament panels continue to work with app/Filament alongside module paths. Panels are additive, so there is no big-bang migration. The unknown is the support matrix: Laravel major × Filament major × laravel-modules major × this adapter. Filament's v3→v4 rewrite materially changed discovery and plugin APIs; a community bridge typically lags by one minor cycle at minimum.

Technical risk.

• Provenance / canonical-source ambiguity (highest concern). The GitHub repo cited is savannabits/filament-modules, but the Composer vendor is theavuthnhel/modules. That is a fork published under a different identity than the upstream it derives from. The 212 stars and any reputation belong to upstream, not to the package we would install. Dependents: 0 on the fork means no downstream field validation of the artifact we would actually ship.
• Bus factor. Effectively one maintainer with a two-upstream churn surface. We inherit every breaking change from both sides, filtered through a single volunteer.
• Blast radius is asymmetric. A failure here doesn't degrade a feature; it can prevent the admin panel from booting (class-not-found during component discovery). Admin-down is a high-severity failure mode for a low-severity dependency.
• Silent authorization gaps. If policies/gates are not resolved correctly from module namespaces, resources can render and function with weaker-than-intended access control. This is the risk most likely to survive a demo and surface in production.

Key questions to answer before committing.

1. Which Filament majors are declared supported, and is there a CI matrix proving Laravel × Filament × laravel-modules combinations, or just a single happy path?
2. Is theavuthnhel/modules the maintained canonical artifact, or a one-off republish of savannabits/filament-modules? What is the upstream sync/merge policy?
3. Does discovery respect modules_statuses.json — i.e., are disabled modules excluded, and does that hold when component discovery is cached?
4. Is the extension surface a documented plugin contract, or a service provider that scans directories? The latter is brittle across minors.
5. Does it support multi-panel assignment per module, panel-level tenancy, and per-module navigation grouping/sort?
6. Test coverage and license/provenance review of the fork (MIT declared; confirm the fork carries upstream notices).
7. Rough LOC of the adapter — this determines whether "vendor it in-house" is a realistic exit, which it almost certainly is.

Integration Approach

Stack fit. Assume PHP 8.1+, Laravel 10/11+, Filament 3.x (verify 4.x), laravel-modules 10/11. Pin exact versions in composer.json and lock the adapter to a specific release — do not float on ^ for a single-maintainer bridge between two moving upstreams. Confirm module PSR-4 autoloading is wired (composer merge plugin or laravel-modules' own registration) before introducing the Filament layer, otherwise every discovery failure looks like an adapter bug.

Prerequisite gate. Decide explicitly: are we a modular-monolith shop? If no, stop here — this is a solution to a problem we would be manufacturing. If yes, the adapter is a candidate. Record this decision; it is the single largest determinant of whether this package pays for itself.

Migration path (incremental, reversible).

1. Spike on a branch. Install, wire one panel, register one trivial module resource. Success criterion: panel boots, resource is discoverable, filament:cache-components + filament:optimize round-trips cleanly.
2. Pilot one low-risk module. Read-only or internal CRUD, no tenancy, no cross-module relations. Validate navigation grouping, policy resolution, and route-name/slug collision behavior.
3. Exercise the lifecycle. Enable/disable the module, re-run discovery caching, deploy to staging. This is where stale-cache failures show up and it is the step teams skip.
4. Widen to 3–4 modules, including one with its own migrations and one with a policy-bearing resource. Re-validate authorization explicitly — do not assume.
5. Only then migrate existing app/Filament resources, one at a time, leaving the app-path discovery in place throughout.

Compatibility sequencing. Do not pair this adoption with a Filament major upgrade. Land it on the current pinned minor, stabilize, then treat any Filament upgrade as a separate change with this adapter called out as an explicit regression-test target. Same for laravel-modules majors.

Exit plan (define up front). The adapter is small enough to vendor. Accept the dependency on the condition that we can take ownership of the discovery wiring in-house within a sprint if the maintainer goes dark or an upstream major lands unpatched. Fork-in-place under our namespace is the fallback, not a rewrite.

Operational Impact

Maintenance. We are not adopting a library; we are adopting a maintenance relationship with a one-person project that tracks two fast-moving upstreams. Budget a recurring line item: a compatibility check on every Filament and laravel-modules minor, plus a smoke test of panel boot and discovery caching. If that budget is not available, vendor the adapter and own it — the ongoing cost is similar and the risk is legible.

Support. No vendor, no SLA. Community issues only, on a repo that may or may not be the artifact we installed. Internal documentation is mandatory: the bridge will be the least-documented layer in the stack, and the person who wired it will not be the person debugging it at 2am.

Scaling. Discovery cost grows with module count but is amortized by component caching — ensure caching is enabled in production and validated in the deploy pipeline. Navigation is the real scaling problem: dozens of module-supplied resources degrade admin UX without enforced conventions (nav group, sort, icon ownership per module). Multi-panel and tenancy need explicit per-module configuration; do not assume the adapter infers intent.

Failure modes to monitor.

• Stale discovery cache after module disable → class-not-found at boot. Mitigation: module enable/disable must trigger discovery cache invalidation as a single atomic deploy step.
• Filament major upgrade → panel fails to boot entirely. Mitigation: pin, test on branch, treat as a planned change with rollback.
• Autoload ordering in CI/deploy → intermittent, environment-specific discovery failures. Mitigation: deterministic composer dump-autoload before cache warm.
• Duplicate slugs / route names across modules → silent overwrite, wrong resource served. Mitigation: namespace convention, asserted in the pilot.
• Policy/gate resolution from module namespaces → authorization gaps that pass smoke tests. Mitigation: explicit authorization test per module resource; make this a merge gate.
• Abandonment → no patches for a broken upstream combination. Mitigation: vendored exit plan.

Ramp-up. Developers need competence in two conventions plus the undocumented seam between them. Plan for a half-day of internal enablement and a short internal README covering: where Filament files live inside a module, how a module registers with a panel, how to enable/disable safely, and how caching interacts with both. This is cheap and it is the difference between the adapter being an asset and being folklore.

Recommendation. Conditional go, gated on the modular-monolith prerequisite. If we are already on laravel-modules, run the two-week spike-to-pilot above; the boilerplate savings are real and the exit cost is low. If we are not, decline — and if the underlying goal is simply "organize a growing Filament admin," solve that with panel discovery and directory conventions, which need no third-party bridge at all.