Filament Coupons Laravel Package

Technical Evaluation

Architecture fit. The package is a Filament panel plugin: its value sits almost entirely in the admin surface — a coupon CRUD resource, form/table schema, and usage-tracking fields (code, type, value, expiry, usage limits, active flag). The strategic question a TPM must force an answer to before scoping anything is whether that surface is all it is. If discount evaluation lives inside Filament actions, the package is admin-only tooling and cannot serve an API checkout, queue job, POS, or any headless consumer. That single fact moves the epic's scope by an order of magnitude and must be resolved in the spike, not assumed from the README.

Framed correctly, the package is a scoping instrument. It ships the commodity half of a discounts epic — "ops can create and retire codes" — and leaves the differentiated half — cart eligibility, stacking/precedence, tax and currency treatment, redemption integrity — to us. That split is the most valuable output of this evaluation: it converts a vague "we need discounts" epic into a bounded v1 with a defensible boundary, and it removes a recurring back-office ask from the backlog permanently.

Fit is strong for a Laravel 10/11 + Filament v3 shop with an existing panel. It is a hard stop for Filament v2 or a non-Filament admin — in that case the package is only interesting as a fork candidate for its schema and model, not as a dependency.

Integration feasibility. Install cost is low (composer require, publish config/migrations, register on the panel). The real cost is ownership of discount semantics. Coupons are cross-cutting: they touch carts, orders, refunds, reporting, and finance reconciliation. Even a clean install implies reconciliation work with the existing order lifecycle, and that work — not the plugin — is what the estimate should carry.

Technical risk. Ranked by what a TPM actually has to manage:

• Release opacity (medium). 1.0.3 ships a compare link and no changelog body. On a dependency that can touch money, an unclassified patch could contain a silent rounding fix. Diff review of 1.0.2→1.0.3 is a gate, not a nice-to-have.
• Bus factor (medium-high). Single maintainer, 4 stars, no stated support window or LTS policy. Acceptable for an internal admin screen with a pinned version; unacceptable as a foundation for pricing logic.
• Money-path correctness (high, only if wired into checkout). No independent evidence of test coverage for expired-mid-session coupons, concurrent redemption, currency mismatch, or negative totals.
• Schema coupling (medium). Published migrations become ours. Upstream column changes in later releases turn into migration work we did not plan for.

Key questions (each needs a named owner and a date, not a vibe):

1. Does the package ship discount calculation or only storage + admin UX? — Eng lead, resolved in spike.
2. What is actually in the 1.0.2→1.0.3 diff? — Eng, day 1.
3. Is there CI, and are money-math paths unit tested? — Eng.
4. Stated Laravel/Filament/PHP support matrix; v4 readiness? — Eng, resolved by composer resolve against our lockfile.
5. Are migrations publish-only or auto-loaded, and is rollback defined? — Eng.
6. Does the maintainer accept private security reports, and what is the license posture? — TPM.

Integration Approach

Stack fit. Target Laravel 10/11, PHP 8.1+, Filament v3, MySQL/Postgres. The first gate is a composer resolve against our real lockfile — a conflict with our Filament or Livewire pin is the most likely early blocker and should be tested before any design work.

Migration path. Sequence deliberately so value lands before risk does:

1. Spike on a disposable branch; publish and run migrations against a copy of the production schema to surface index and collation conflicts.
2. Ship admin-only first: ops create, list, activate, and retire codes with no checkout wiring. This delivers the marketing-unblocking value at zero money-path risk and is independently useful even if the rest is descoped.
3. Integrate evaluation into cart/order behind a feature flag, wrapped in our own service interface, so swapping implementations never touches call sites.

Compatibility. Treat the coupon and redemption tables as internal to the package. No other service joins to them directly; reads go through our repository/API layer. This is the cheapest insurance against a schema migration we do not control, and it is a design constraint to state in the ticket, not a preference.

Sequencing.

• Week 1 — diff review, dependency resolution, license check. Gate: all three clean, or stop.
• Week 2 — spike plus schema-copy migration. Gate: answer to key question 1.
• Week 3 — admin-only rollout to internal ops. This is the shippable milestone to put in the roadmap.
• Weeks 4–6 — checkout integration behind flag with a documented kill switch.
• Pin to an exact version. No ^1.0 until we have a release-review habit with a named owner.

Budget ask to pair with this: roughly one engineering day for the spike, two to three days for checkout integration, plus a recurring half-day per upstream release for review. That is the honest number to put next to "days, not sprints."

Operational Impact

Maintenance. An empty changelog means we cannot diff-and-decide; every release requires a manual commit-history review. That is recurring, uncompensated time — budget roughly a half-day per release. Add the package to a vendor register with: pinned version, named code owner, last-reviewed date, and the trigger condition for a fork review (six months of upstream inactivity). Unowned money-adjacent code is the failure mode to design out on day one.

Support. Upstream is best-effort GitHub issues; the escalation path is maintainer → fork. A TPM must force the political question early: is forking acceptable to this org? If not, this is a hard dependency on one person and should be documented as such in the risk register. If yes, vendor the package now and stop pretending it will be upstreamed.

Scaling. Admin UI is page-bound and scales fine. The pressure point is checkout: ensure a unique index on code and a composite index on (customer, coupon) for usage-limit checks. The redemption-count check is the contention point — plan for an atomic increment or a dedicated redemption table with a unique constraint rather than read-then-write. That is a known v1.1 item, not a surprise.

Failure modes, with mitigations a TPM can actually track:

• Silent discount miscalculation — highest severity, lowest detectability. Mitigate with an invariant test suite on order totals and a daily reconciliation job comparing expected vs. applied discounts. This is the control finance will ask about; have the answer ready before they do.
• Concurrent redemption — two sessions consume a single-use code. Requires DB-level uniqueness, not an application check.
• Abandoned upstream — pinning becomes permanent and PHP/Filament upgrades block. Fork review at six months of inactivity.
• Migration drift — our copy diverges from upstream's and future upgrades produce destructive diffs. Prevented by the internal-tables rule above.

Ramp-up. A Filament-fluent Laravel developer is productive on the admin surface in under a day. Checkout integration requires reading the package source, not the README — budget two to three days and assume the docs cover only the happy path. Do not staff this with someone who has not handled money in Laravel.

Recommendation. Approve a time-boxed, one-day spike and greenlight admin-only adoption as an independent deliverable. Hold any checkout-path commitment until key question 1 is answered and the 1.0.3 diff has been read. Admin-only use is low risk and removes a live backlog item; the plugin is not yet a safe default for the payment path, and the roadmap should say so explicitly rather than implying a full discounts capability ships with it.