Tartarus Laravel Package

Technical Evaluation

Architecture fit

• Resolve the identity of the package before anything else. Repository metadata says "simple multi tenants"; the documentation describes a Filament-native recycle bin over soft-deleted Eloquent records. These are two entirely different products with different risk profiles. The recycle-bin reading is the one backed by documentation and consistent with the Lara Zeus family of Filament admin conveniences. Treat "multi tenants" as stale metadata, but confirm by reading src/ — not the README — before it enters a planning document. If tenancy is the requirement, this is not the package; the correct comparison set is stancl/tenancy or spatie/laravel-multitenancy.
• Assuming the recycle-bin shape, the architecture fit is narrow and clean: it sits on top of Laravel's SoftDeletes trait and surfaces restore/force-delete through Filament. It is an admin-surface package, not infrastructure. It does not change how your domain models persist, so it does not force an architectural decision beyond "do we use soft deletes here."
• The dependency it creates is real but shallow. The genuine coupling is to (a) Filament's version line and (b) Laravel's soft-delete semantics. Neither is exotic. The package is small enough that the source is cheaper to read than to trust, and that reading is the actual due-diligence exercise.
• Fit is contingent on Filament. If the admin/support surface is Filament-based, this is family-coherent: shared conventions, styling, upgrade cadence. If it is not, this package is a small part of a much larger adoption decision (adopting Filament) and should be framed that way rather than discovered mid-sprint.

Integration feasibility

• Feasible, with a half-day validation gate. Install, publish config, publish migrations, migrate on a throwaway branch, attach the trait to one soft-deletable model, delete from tinker, confirm it appears in the bin, restore, force-delete. That sequence is the go/no-go.
• The published config is the honest API surface. Retention window, model discovery, and pruning behaviour live there. Reading it end to end tells you more than the README and, importantly, answers whether the package keeps its own table or simply leans on deleted_at. That single fact determines the whole integration strategy.
• Restoration is a domain operation, not a column flip. Laravel's restore() clears deleted_at and nothing else. Any deletion with side effects — cancelled subscription, revoked invite, archived file, sent notification — needs a compensating action on restore. This is our work, not the package's, and it is the single largest hidden cost in the estimate.

Technical risk

• Zero dependents means we are the QA function. Ten stars, no dependents, and a 2.0.1 changelog consisting of Dependabot bumps plus a Filament compatibility fix. That is housekeeping, not hardening. Nobody upstream is finding the edge cases; our tests will be the first to encounter them.
• Unique-constraint collisions on restore (high likelihood). Delete a user with [email protected], someone re-registers with it, restoring the original violates the unique index. The package cannot solve this. Per-model policy required: block with a clear notification, merge, or suffix.
• Multi-tenant row scoping (high severity, conditional). If the application is multi-tenant, the bin must respect tenant_id. If the package's internal queries use withoutGlobalScopes() — common in admin tooling to avoid scoping surprises — a support user could restore a record into visibility they should not have. Grep the source for withoutGlobalScopes, withoutGlobalScope, and raw DB::table( before shipping. This is the highest-severity item in the whole evaluation.
• Force-delete blast radius. The scariest button in the admin panel. It needs a policy gate, a type-to-confirm modal, and for financial or regulated records, a hard rule that it is unavailable in production or requires two people.
• Relation and cascade integrity. restore() on a parent does not restore children; force-deleting a parent whose children were force-deleted or orphaned is the failure mode. FK onDelete behaviour must be checked against what the package actually issues.
• Pruning is a silent-failure risk. A scheduled prune that quietly stops is indistinguishable from one that works until disk fills or a compliance request arrives. Explicitly decide whether pruning force-deletes or relocates; determine that from source, not docs.

Key questions

1. Is this a recycle bin or a tenancy package? Answered only by reading src/.
2. Does the package maintain its own deleted-records table, or does it read deleted_at directly?
3. Do its queries inherit our global scopes, or bypass them?
4. Does it ship automatic pruning, and does pruning force-delete?
5. Which Filament major version does it track, and does that match our pinned version?
6. What is the extension surface for restore hooks — events, action classes, or Filament action callbacks?
7. Is the source small enough to fork cheaply, and do we have the test coverage to know when a fork is warranted?

Integration Approach

Stack fit

• Laravel + Filament is a hard prerequisite. Without Filament there is no UI and the package delivers very little against its own value proposition.
• SoftDeletes coverage across the domain is the real substrate. Audit which models currently use it before promising a "recycle bin for everything." Adding the trait is a schema-adjacent change with withTrashed(), unique-index, and relationship implications that propagate.
• The package is a UI convenience layer. It does not replace an audit trail. If the requirement is "who deleted what and why, permanently" — that is event sourcing / activity logging territory and should be scoped separately, not conflated with "undo."

Migration path

1. Spike branch. Install, publish config and migrations, read the published config and migration in full.
2. One model. Pick the highest-anxiety, most-deleted model (order, invoice, customer, post). Wire it end to end.
3. Demo internally. Support staff find the record in a "Recycle Bin" page, see when it was deleted, click Restore, no developer involved. That demo is the business case; if it does not land in an afternoon, we have lost an afternoon and learned something cheap.
4. Tier 2 expansion. Add models incrementally, never all in one PR — inheriting unique-constraint and relation-restore problems across the whole schema at once leaves us with no baseline.
5. Retention policy decision. Written answer: 30 / 90 / forever. This is a product promise, not a config value.

Compatibility

• Pin the exact version in composer.json. The upgrade cadence is Dependabot-driven, so version drift is not a hardening signal and should not be treated as one.
• Filament major-version tracking is the primary breakage vector. Confirm alignment with our pinned Filament version before committing.
• Laravel 11+ vs. earlier affects where pruning is scheduled (routes/console.php vs. Kernel::schedule()).
• Livewire request lifecycle: verify the restore action behaves correctly on re-render, not just on first invocation.

Sequencing

1. Source read + identity confirmation (30 min, blocks everything).
2. Config and migration read (blocks migration strategy).
3. Single-model spike with a delete → appear → restore → force-delete loop.
4. Policy work: canForceDelete(), restore guards for unique constraints, restore observers for parent/child models.
5. Tenant scoping audit, if applicable — before any multi-model rollout.
6. Pruning schedule + monitoring.
7. Tier 2 model expansion.
8. Per-model feature test: delete, assert present in bin for authorised user, restore, assert intact with relations.

Extension points, in order of preference: Filament action hooks and lifecycle callbacks → model observers and events → published config → subclassing the shipped resource → forking. The first two cover most needs and survive upgrades; the last two are where upgrade cost accumulates.

Operational Impact

Maintenance

• Low code footprint, low maintenance surface — but maintenance is ours, not the community's. With zero dependents, there is no upstream bug-finding. The practical mitigation is a fork plan: MIT licence, small source, cheap to fork. That is a genuinely good mitigation, but only if we have the tests that tell us when a fork is needed.
• Dependabot-driven releases mean the changelog is not a reliable indicator of behavioural change. Diff the source on upgrade; do not read the changelog and assume.
• One feature test per model in the bin is the cheapest insurance available and survives both package upgrades and forks.

Support

• This is the package's core value: converting "I deleted the wrong record" from a direct-DB-edit or one-off-script ritual into a button click by a support agent. Quantify the business case from ticket history — recurring manual-restore requests are the number that justifies the adoption.
• A navigation badge showing trashed-record count is the difference between a bin support actually checks and one nobody uses. Wire it if a query scope is exposed.
• Log restores with the acting user. "Who put this back" appears in every incident review and should not be reconstructed after the fact from activity_log.
• Restoration must be idempotent. Support will click twice; scheduled jobs may resurrect records concurrently.

Scaling

• Read-path scaling is a Filament table with search, filter, and pagination over onlyTrashed() queries. Standard admin-table scaling concerns; index deleted_at on high-volume tables.
• Write-path impact is negligible — soft deletes already existed or did not.
• Pruning at scale is the real cost: a large force-delete batch can lock tables and spike I/O. Run it on a queue worker with the correct DB connection, in batches, off-peak, and monitor it.
• Queues and artisan commands bypass request context. If any restore or prune logic touches auth()->user() or session state, it will be null or wrong. Pass the acting user ID explicitly into dispatched jobs.

Failure modes

Ramp-up

• Engineers: ~1 hour to read the source and config; ~half a day to a working single-model spike. Small enough that reading it is cheaper than trusting it.
• Support/CS: near-zero — the UI is a Filament table with restore and force-delete actions. The training need is entirely about force-delete discipline and knowing which models are not in the bin.
• Product/Compliance: the retention-window decision needs an owner and a written answer before launch, not after. Discovering the answer accidentally during a customer security review is the expensive path.

Recommendation for a TPM: treat this as a low-cost, high-clarity pilot with a hard validation gate. Approve a half-day spike on one model, contingent on the source read confirming the recycle-bin shape and the tenant-scoping audit coming back clean (or the app being single-tenant). Do not approve a broad rollout until the retention policy is written down, force-delete is policy-gated, and per-model tests exist. The upside is modest but real — a class of support tickets disappears. The downside is bounded, because the package is small enough to fork or abandon at low cost. The one thing that must not be discovered late is tenant scoping: on a multi-tenant system, that is a security issue, not a convenience one.