Modules Laravel Package

Product Decisions This Supports

• Modular monolith vs. microservices / multi-repo. Provides a concrete path to keep one Laravel deployable while enforcing domain boundaries (billing, inventory, CRM) as autonomous modules — each owned by a squad and each surfaced as its own Filament plugin. This is the decision this package most directly de-risks.
• Admin IA and navigation architecture. clusters.enabled plus clusters.use-top-navigation let you decide between cluster-per-module navigation vs. flattening into the existing side nav; panels.group, panels.group-icon, panels.group-sort and panels.open-in-new-tab let you decide whether module surfaces are grouped, nested, or launched as separate consoles. These are product/UX calls, not just technical ones, and they're config, not code.
• One admin vs. many panels. module:make:filament-panel supports per-module panels, which maps cleanly onto back-office-plus-customer-portal, per-brand white-label admin, or per-tenant consoles — without standing up separate apps.
• Registration/runtime model. mode (plugins / panels / both) and auto-register-plugins decide whether module surfaces appear automatically or are curated per panel. That is the lever for "every module ships its own admin" vs. "we gate what goes live per release."
• Build vs. buy (buy, cheaply). MIT-licensed wrapper over nwidart/laravel-modules; the incremental cost is one composer require and one ModulesPlugin::make() registration. You are not building a module loader or an admin-plugin bridge — you are adopting two upstream conventions.
• Reuse and portfolio economics. For agencies/product studios, modules become shareable across client projects and a genuine asset library; for SaaS, feature modules become sellable add-on tiers.
• Time-to-ship for new admin surface. Artisan generators for resources, pages, widgets, clusters and plugins mean a new module's admin CRUD is hours, not a sprint — useful for roadmap sequencing where admin is the long pole.

When to Consider This Package

Adopt when:

• You have already committed to (or are seriously evaluating) nwidart/laravel-modules. This is a wrapper, not a replacement — the prerequisite setup and merge-plugin autoloading are non-negotiable.
• You are on Laravel 11/12/13 with Filament 4.x/5.x and PHP 8.3+. The version matrix is explicit; older stacks mean pinning to the 3.x/4.x branches and accepting frozen feature sets.
• You expect module boundaries to multiply (multiple squads, multiple client projects, or add-on feature packs) and want those boundaries reflected in admin without hand-registering plugins.
• You can absorb the "WIP" surface: widgets, themes, and the access-control base classes (Coolsam\Modules\Resource, Page, TableWidget, ChartWidget, StatsOverviewWidget, CanAccessTrait) are explicitly marked work-in-progress. Treat them as prototypes, not pillars.

Look elsewhere when:

• Authorization is a near-term requirement. Access control here is WIP — do not build a compliance, RBAC, or audited-permissions story on these base classes today. Keep native Filament policies/Gates as the source of truth.
• You don't have real module boundaries. A single-team CRUD admin is fully served by vanilla Filament panel plugins with zero extra dependencies.
• You need vendor support, an SLA, or a named maintainer. One primary author, 212 stars, and zero dependents in the ecosystem is a pilot signal, not an enterprise signal.
• You're mid-migration on Filament majors, or your release cadence can't track upstream churn. You inherit a two-level dependency (package → nwidart/laravel-modules → Filament), and each major bump on either side is a coordinated upgrade.
• Filament's own discovery and multi-tenancy primitives already cover you — the README is candid that this package wires modules and panels together but does not override Filament's per-panel registration model.

How to Pitch It (Stakeholders)

To executives: This is a small, MIT-licensed adapter that lets us organize our admin panel by business domain instead of by file type. It converts our module structure into self-contained admin plugins, so a new feature area ships with its own screens, navigation, and permissions surface in one move — and reusable modules can be carried across products or clients. Cost is one dependency and a configuration file; the return is faster admin delivery and a codebase where domain ownership is visible in the UI. The risk to acknowledge honestly is maturity: single maintainer, low adoption footprint, and a few features still marked WIP — so we adopt it behind a pilot scope, not as a platform-wide mandate.

To engineering: It's a thin wrapper around nwidart/laravel-modules. One ModulesPlugin::make() in the panel provider, one php artisan modules:install, and every module becomes a Filament plugin with its own resources, pages, widgets and clusters. The generators are first-class Artisan commands, so nothing new to learn beyond the prompts. Config is centralized in config/filament-modules.php — mode, auto-register-plugins, cluster and panel grouping — which means we can change registration behavior without touching module code. No fork of Filament, no overridden discovery, no magic. We pin the major version and treat access-control base classes as experimental until they're out of WIP.