Hades Laravel Package

Technical Evaluation

Architecture fit

• lara-zeus/hades is a Laravel package delivered through the framework's service-provider/package-discovery conventions and surfaced inside a Filament panel. Its architectural fit is therefore a function of the host application's Filament major version, not of Laravel itself.
• Release 3.0.0 rebases the package on Filament v5. That makes 3.x a good fit for greenfield panels or panels already committed to a Filament v5 upgrade, and a poor fit for any application still on Filament v3 or v4.
• The major version number is doing real work here: a Filament major bump typically carries panel-registration API changes, schema/form component changes, and asset-pipeline changes. Assume 3.0.0 is not a drop-in for a 2.x install until proven otherwise.

Integration feasibility

• Straightforward in a Filament v5 panel: composer require, publish config/migrations/assets, register the plugin on the panel provider, run migrations.
• Constrained in existing installs: the package version is now coupled to the platform version, so adoption is gated on a Filament upgrade project that is almost certainly larger than the package upgrade itself.
• Low effort to evaluate (install in a scratch app), high effort to adopt (requires the Filament major migration first).

Technical risk

• Breaking change with no migration guidance. The release notes are two bullets: a Filament v5 bump and a docs restructure. There is no documented list of changed public APIs, config keys, published asset paths, or database migrations. A semver major without a changelog is an unquantified risk.
• Version lock-in / support cliff. If 2.x is effectively frozen, apps that cannot move to Filament v5 are stranded on 2.0.1 with no security or bugfix path. This is the single largest operational risk.
• Docs restructure collateral. "Align docs structure and cleanup" can silently break deep links, anchors, and any internal runbooks or onboarding docs that reference specific pages — with no redirect guarantee.
• Single-vendor dependency. lara-zeus is a small-team ecosystem; a major-version cadence forced by every Filament major means the upgrade treadmill is set by an upstream you do not control.
• Evidence gap. No prior assessment exists and the package data supplied is empty, so this evaluation rests entirely on two release-note bullets. Confidence is low-to-moderate; the risk rating should be revisited once the actual diff and README are reviewed.

Key questions

1. Does 3.0.0 require Filament v5 exclusively, or does the composer constraint still allow v3/v4 (i.e. is the major bump precautionary or hard-breaking)?
2. Is there a maintained 2.x branch, and for how long — bugfixes only, or security fixes too?
3. What are the concrete breaking changes beyond the dependency bump: renamed config keys, changed namespaces, new/removed migrations, changed plugin registration signature?
4. What are the minimum PHP and Laravel versions for 3.0.0, and do they conflict with our platform baseline?
5. Are the docs now versioned (v2 vs v3), and are old URLs redirected?
6. Is 3.0.0 a fresh release with a follow-up patch cadence expected, or a stable cut? Any known issues in the Filament v5 migration?

Integration Approach

Stack fit

• Target stack: Laravel (version per the package's composer constraint) + Filament v5 panel + PHP version per constraint. Confirm the constraint matrix against our pinned Laravel/PHP before scheduling anything.
• If our panels are on Filament v3 or v4, 3.0.0 is not currently a stack fit and should not be adopted opportunistically.

Migration path

1. Do not bump to 3.0.0 as a routine dependency update. Treat it as a platform upgrade project.
2. Pin lara-zeus/hades to ^2.0 in composer.json on all current branches and confirm the lockfile is committed, so a transitive or loose constraint cannot silently pull 3.x.
3. Inventory where the package is used: which panels register it, which resources/pages depend on it, and which config keys and published assets we override.
4. Upgrade Filament to v5 in an isolated branch first, with the package still on 2.x excluded — i.e. determine the Filament migration cost independently of this package.
5. Only then bump hades to ^3.0, re-publish config and assets, and diff the published files against our overrides.
6. Run a regression pass over every admin surface the package renders, plus a database migration dry run against a production-like snapshot.

Compatibility

• Expect a hard matrix: Filament v3/v4 → hades 2.x; Filament v5 → hades 3.x. Mixed-version support in a single package line is possible but should not be assumed from these notes.
• Composer will surface conflicts at install time, which is good — the failure will be loud, not silent.

Sequencing

• Order of operations: pin 2.x → confirm 2.x support window with maintainers → scope Filament v5 upgrade independently → upgrade Filament → upgrade hades → re-publish and diff config/assets → regression test → update internal docs/runbooks.
• Do not parallelize the Filament and hades upgrades; if something breaks you will not be able to attribute it.
• If the Filament v5 upgrade is not on the roadmap this quarter, close this out as "pinned, deferred" and revisit only if 2.x support is withdrawn.

Operational Impact

Maintenance

• Expect a major version of this package per Filament major. That converts an upstream framework cadence into recurring planned work for us, whether or not we need new features.
• Mitigate by keeping our footprint minimal: avoid forking, avoid patching vendor files, keep overrides to published config only. Every local customization is a recurring cost at each major.
• The docs restructure is low-cost if we keep our own runbooks self-contained rather than linking out to the package's docs site.

Support

• The critical unknown is the 2.x support window. Without a stated policy, plan on the assumption that 2.x receives no fixes, and treat "staying on 2.x" as a time-boxed position requiring an exit date.
• Small-maintainer risk is real: a two-bullet major release suggests limited release-management bandwidth. Budget for reading the diff ourselves rather than waiting for a migration guide.
• Escalation path is upstream GitHub issues only; there is no commercial support to lean on.

Scaling

• Package-level scaling is not a concern — it is an admin-panel surface, not a hot request path. Any performance characteristics are inherited from Filament v5 and our own query patterns in custom resources.
• The scaling concern that does apply is organizational: number of panels and number of customized resources multiplies the regression surface at each major upgrade.

Failure modes

• Dependency conflict at install: composer refuses to resolve hades 3.x against a Filament v3/v4 constraint. Loud, safe, easily diagnosed.
• Stale published assets/config after upgrade: old config keys left in place, or cached config/assets not republished, producing confusing runtime behavior that looks like a package bug.
• Silent behavioral drift: with no changelog, a renamed config key or changed default may degrade functionality without erroring. This is the highest-severity failure mode because it is quiet.
• Stranded on an unsupported 2.x: a Laravel/PHP security upgrade later forces a Filament v5 migration on someone else's schedule.
• Broken documentation links in onboarding material and incident runbooks following the docs restructure.
• Migration/rollback gaps: if 3.0.0 ships database changes, confirm they are reversible before running against production.

Ramp-up

• Low for engineers already fluent in Filament: the package is conventional and panel registration is familiar. The docs cleanup likely improves first-run experience for newcomers.
• Moderate-to-high for upgraders: the absence of a migration guide means the learning cost lands on whoever reads the diff, and that cost is paid again by each team that upgrades.
• Recommend one engineer own the upgrade end-to-end and produce an internal migration note — that artifact is the real deliverable, since upstream has not provided one.
• Given the thin evidence base, treat this assessment as provisional and re-run it once the 3.0.0 diff, composer constraints, and versioned docs have been reviewed directly.