Modulite Laravel Package

Product Decisions This Supports

• Build vs. buy on admin assembly glue. The underlying problem — "every new module must touch a shared PanelProvider file to get its resources, pages, and widgets registered" — is real, recurring, and low-differentiation. Modulite is a ~150-line-of-integration answer to it. This is a decision to not staff a platform ticket, not a decision to adopt a strategic platform.
• Whether to scale the modular architecture to more panels. Value scales with modules × panels. If our roadmap adds a partner panel, a support/ops panel, or a customer-facing Filament panel on top of internal admin, manual registration cost grows multiplicatively. Modulite turns that into a directory convention (modules/User/Filament/{panel}/…), which is the difference between "new panel = a sprint of wiring" and "new panel = one provider + a config path." That is a roadmap-enabler argument, not a code-quality argument.
• Feature-level decision: per-module admin surface. It makes "ship a module with its own admin CRUD" a single-ticket deliverable. That directly affects whether we can let squads own modules end-to-end or whether every module's admin surface needs a platform-team handoff. Use that as the org-design lens in planning.
• Convention-as-product decision. The validation.strict_inheritance / allow_custom_base_classes settings let us encode our admin conventions as enforced config rather than a wiki page. That's a governance lever worth a decision: do we want conventions enforced at discovery time (large/multi-team) or permissive (small team, fast iteration)?
• Deploy-pipeline decision. modulite:cache is a required build step with a bootstrap/cache/modulite.php artifact, and with TTL=0 in production that artifact is authoritative until manually cleared. This creates a concrete deploy checklist item and a release-gating question: does the cache get rebuilt on every deploy, and does a post-deploy smoke test assert panels are non-empty? Do not adopt without answering yes to both.
• Incident-response and rollback decision. The v1.1.3/v1.1.4 history is the decision-relevant fact: a silently failed scan returned an empty panel list that was cached with no expiry, taking every panel offline until someone cleared the cache manually. Fixed, but it tells us the failure mode of this class of package is total admin outage, not degraded UX. That should drive a rollback plan (manual-registration fallback path, config to disable caching, documented modulite:cache --force) decided before adoption, not after.
• Use cases it genuinely fits: multi-tenant SaaS with an internal admin plus a tenant/partner panel; a product moving from monolith admin to module-per-domain; a platform team supporting several squads shipping Filament features.

When to Consider This Package

Consider it when all of these are true:

• We already run a modular Laravel layout on nwidart/laravel-modules or panicdevs/modules — this is not a reason to adopt modularity, only a reason to adopt the glue.
• We run two or more Filament panels, or have a committed roadmap to a second panel within two quarters.
• Enough modules carry admin surfaces that manual registration is genuinely a recurring ticket (rule of thumb: 5+ modules, or 2+ engineers regularly editing the same provider files and hitting merge conflicts).
• Filament 4 or 5 and PHP 8.2+ — this is a hard gate; on Filament 3 the package is irrelevant.
• We are comfortable with convention-based discovery, i.e. file placement determines behavior, and the team will internalize "components must end in Resource/Page/Widget under the right panel directory."
• We can own a deploy step and a post-deploy smoke check.

Look elsewhere / decline when:

• Single panel, few modules. The package adds a config file, a cache artifact, a deploy step, and a failure mode to save a handful of lines. Negative ROI. Manual registration is fine and has better discoverability for new engineers.
• Registration logic is not purely conventional. If panels are assembled dynamically per tenant, gated by entitlements, or composed at runtime, a filesystem scan is the wrong abstraction and we'll be fighting auto_register => false and manual fallbacks anyway.
• We need vendor guarantees. 22 stars, zero dependents, single-maintainer package, breaking change at v1.0.0, and two production-outage-class bugfixes in consecutive patch releases (v1.1.2, v1.1.3/1.1.4). That's a normal early-stage trajectory, but it is not a dependency to put under a revenue-critical admin without a pinning strategy and a fallback. If the organization's vendor-risk policy requires SLAs or a support contract, this fails on principle.
• Team is small and unfamiliar with Filament internals. Debugging "why didn't my widget register" through a cache layer and a status --vvv command costs more than one line in a provider for a 2–3 person team.
• We're mid-migration or on an unstable Filament major. Filament v5 support landed in a patch release (v1.1.1), which suggests version-support is reactive rather than pre-announced.

If adopted, the PM-level conditions: pin an exact version, add modulite:cache to the deploy pipeline, add a smoke test asserting each panel returns a non-empty component set, keep caching disableable via env for incident response, and write down the manual-registration escape hatch in the runbook before go-live.

How to Pitch It (Stakeholders)

For executives — the one paragraph: Our admin surface is assembled by hand: every new module requires edits to shared panel provider files, which creates merge conflicts, serializes work on a small number of people, and makes adding a second admin panel a multi-sprint effort. Modulite replaces that with a directory convention, so a module that follows our structure registers itself. It's a small, low-cost dependency with no infrastructure footprint — no database, no service, no runtime daemon — and its cost is one deploy step. The tradeoff is that it's an early-stage open-source package maintained by a single author, so we'd pin the version and keep a documented fallback. Recommendation: pilot it in a non-critical branch of the admin platform, measure the registration toil it removes over one quarter, and only then make it a platform standard. Expected payoff is engineering throughput and merge-conflict reduction, not user-facing features.

For engineering — the summary: Filament panel providers and their resources/pages/widgets are currently registered by hand. Modulite discovers PanelProvider classes and per-panel components by convention across nwidart/laravel-modules or panicdevs/modules, driven by one published config. Integration is composer require, publish config, add ModulitePlugin::make() to ->plugins([...]) in each panel, and run modulite:cache at deploy. Components map to panels by directory (modules/User/Filament/Admin/Resources/… → the admin panel), with * and {panel} placeholders in discovery paths. Caching mirrors Laravel's bootstrap cache: bootstrap/cache/modulite.php, cleared by optimize:clear or modulite:cache --force, with modulite:status [--vvv] for diagnostics. Warm-cache overhead is sub-millisecond; cold scan is single-digit-to-low-double-digit milliseconds depending on module count — performance is not the concern.

The concern is operational blast radius. In production the cache has TTL=0, meaning it does not expire. Two consecutive patch releases fixed a class of bug where a silently failed scan produced an empty panel set that was then cached indefinitely, taking all panels down until a human cleared the cache. That's now addressed — results are only cached on a clean scan — but it establishes the failure mode: a bad scan is a total admin outage, not a degraded page. So the ask before adoption is not "approve the dependency," it's "approve these three mitigations": (1) a post-deploy smoke check that asserts each panel discovers a non-zero component count, (2) caching disableable via MODULITE_CACHE_ENABLED=false as a documented break-glass lever, and (3) a written fallback to explicit provider registration. With those in place, this is a reasonable bet; without them, it's an unmonitored single point of failure in the admin path.