Tomato Ecommerce Laravel Package

Technical Evaluation

Architecture fit. The package is an admin-panel-first commerce module, not a headless commerce engine. Its models, migrations, and resources are shaped around Filament and the TomatoPHP module loader. That is a strong fit only if our monolith already runs Filament and we are prepared to keep running it — the package borrows our admin panel rather than shipping its own. If our roadmap implies an API-first storefront, a multi-vendor marketplace, or multi-tenant commerce, this is a mismatch and should be closed out early rather than carried as a "maybe."

Where it fits, it fits a specific slot: catalog, cart persistence, order records, and back-office CRUD in weeks instead of quarters. The description claims products/categories, cart and checkout flow, order management, and Filament integration. Treat every one of those as vendor-claimed, needs verification. The release history provides no evidence of what is genuinely implemented — payments, tax, shipping rates, refunds, and inventory reservation are almost certainly ours to build, and the package itself frames the boundary as "extensible architecture for custom pricing, payments, and workflows."

Integration feasibility. Technically straightforward in a Laravel/Filament host: Composer install, publish config and migrations, run migrations, walk the golden path in Filament. Integration risk is not in the install; it is in (a) brownfield schema collisions if we already own products, carts, or orders tables, and (b) version lockstep across the tomatophp/* family against a shared Filament constraint.

Technical risk. Ranked by expected cost:

1. Ecosystem lockstep. TomatoPHP modules move together. An unrelated module patch can force a bump here, and the failure mode is a white-screened admin page, not a clean Composer error. Mitigation is policy, not code: pin every tomatophp/* package to exact tags, and rehearse family upgrades on a branch with the panel clicked through.
2. Release hygiene. v1.0.8 is a single commit whose message is "update icon," with no API or migration detail. There is no usable changelog. Every upgrade requires a human reading git diff on src and database, and a two-second git show <tag> -- composer.json to catch hidden constraint bumps. This is a recurring, non-zero time tax we must budget as a line item.
3. Revenue-path correctness. Assume no row locking (concurrent checkouts oversell the last unit), no idempotency on webhooks (provider retries double-charge or duplicate orders), and no totals snapshot on orders (historical invoices become indefensible when prices change). These are the failure modes that reach customers and finance, and they must be closed before launch regardless of what the package ships.
4. Adoption signal. 3 stars, 0 dependents, last release April 2024. This is a single-maintainer, low-traffic package. We are not buying a community; we are buying source we can read. Plan to own the code path, not to lean on upstream support.

Key questions (answerable in a one-week timeboxed spike in a throwaway app, producing a capability matrix plus a schema diff — not a demo):

• Which of the claimed capabilities are implemented versus stubbed? Walk product create → cart add → checkout → order and mark each step.
• What are the declared php, laravel/framework, and filament/filament ranges, and do they intersect with ours?
• Does the schema collide with tables we already own? If so, is running alongside cheaper than mapping in?
• Is money stored as raw decimal/unformatted, and are prices tax-inclusive or exclusive?
• Does an order store a totals snapshot at time of purchase?
• Does the package dispatch events on cart/order change, or do we fire our own from a service layer?
• Are migrations reversible without data loss?
• Do generated indexes cover SKU, order number, and status? (Admin list pages at 50k orders are where "working" installs time out.)

Integration Approach

Stack fit. Laravel + Filament + TomatoPHP admin. Keep the package's models as persistence and put a thin application-level service (App\Services\CheckoutService) between our controllers and the vendor models. That service is the blast radius absorber for upstream patches — cheap insurance given the release cadence.

Migration path. Two viable paths, and we pick one explicitly and write it down:

• Greenfield-adjacent (recommended default). Let the package own its own tables, run its migrations as-is, and add our extensions via new migrations and side/profile tables (HasOne order profile) rather than editing published files. Never edit a published migration — the next upgrade silently reverts it.
• Brownfield with existing commerce tables. Diff the generated schema against ours before writing code. Mapping into existing revenue tables is usually more work than running alongside, and syncing two order tables is usually the wrong answer for money data. If we already have orders, the honest recommendation is often to close this evaluation rather than reconcile two sources of truth.

Compatibility. Pin tomatophp/tomato-ecommerce:1.0.8 exactly — no caret range. Commit the lockfile change on its own branch so a Filament/Laravel constraint conflict fails in isolation instead of inside a feature PR.

Sequencing. Back office first, storefront second. Phase one is operational and low-risk: catalog management, order visibility, manual fulfillment, internal tooling. Phase two is customer-facing checkout, gated on the payment/tax/shipping adapters being real. That order matches both the package's architecture and the risk profile — the expensive unknowns are all on the customer-facing side.

Boundary we own, not the package. Payment gateway calls, tax calculation, shipping rates, webhook handling, refunds, inventory reservation, and any non-Filament storefront UI. Build payments behind a single PaymentGateway contract (charge, refund, verifyWebhook); create orders in pending, redirect, and let a queued webhook job confirm. Idempotency key on order creation, unique index on the provider's transaction ID. Do not let a stakeholder read "full e-commerce system" as "Stripe is included."

State machine. Add a small enum plus a guard method that rejects illegal transitions (pending → paid → fulfilled; refund as a branch, not a rollback). Log every transition with actor and timestamp. Cheap now; prevents the refunded-after-shipment dead-end later.

Feature flag and shadow mode. Wire routes and checkout behind config('features.new_checkout'). If this replaces an existing flow, run shadow mode: real orders continue through the old path while parallel records are written through the new one, diffed daily for a week. That is the only reliable catch for total-calculation drift before it costs money.

Testing. One feature test per golden-path step under RefreshDatabase. Build factories for the package's models on day one if none ship — we will need them constantly.

Operational Impact

Maintenance. This is the dominant ongoing cost and it is not zero. Ownership model must be explicit: we own the published migrations, the diff-review ritual for every upgrade, and the service layer around payments and totals. Allocate recurring capacity — roughly a half-day per upgrade cycle plus a full-family rehearsal per quarter — and name an individual accountable for reading git diff v0.x..v0.y -- src database before each bump. Without a named owner, this package degrades quietly: it works until an unrelated TomatoPHP patch white-screens the admin panel.

Support. Effectively none. Single maintainer, 3 stars, 0 dependents, no changelog. We cannot file a support ticket; we can read source, fork, or absorb. Set that expectation with stakeholders explicitly and early — this is an adopt-the-source decision, not a vendor relationship. MIT license means forking is legally clean, which is a genuine mitigation, but a fork converts maintenance cost from "review diffs" to "own the module," and that should be a conscious choice rather than an accident.

Scaling. Two distinct concerns:

• Admin surface. Filament list pages over large order and product tables will N+1 and full-scan. Verify indexes on SKU, order number, and status; add our own if missing. Watch the query log while paginating 50k orders — that is the specific point where an install that "worked" starts timing out. This is an afternoon of work if caught at the spike, a sprint if caught in production.
• Checkout concurrency. Assume no locking or stock reservation until proven otherwise. Add lockForUpdate() around stock decrement inside a transaction, or a reservation table with expiry, and test with a real concurrency harness — not a unit test. This is the difference between a launch and an oversell incident.

Failure modes to monitor, in the order they'll bite:

1. Silent queue failure. If confirmation, email, and payment verification run on the queue, a dead worker produces orders that exist but never confirm — no error, no alert, just customer complaints. Alert on queue depth and failed-job count; do not rely on a dashboard someone checks weekly.
2. Duplicate charges / duplicate orders. Provider webhook retries without idempotency. Guard with a unique constraint on provider transaction ID plus an idempotency key at order creation. This is the failure mode that makes the news.
3. Totals drift. Compare the stored order snapshot against recomputed totals as a routine check. Most "checkout is broken" reports resolve here.
4. Admin panel white screen. Lockstep version conflict. Caught by rehearsing family upgrades on a branch with the panel loaded.
5. Rollback surprise. Confirm migrate:rollback behavior in a disposable app. If the down path leaves orphaned tables or drops data we believed was ours, we need a documented restore procedure before production, not after.

Ramp-up. Low for any engineer already fluent in Laravel and Filament — a day to walk the golden path, a week to a documented capability matrix. The learning curve is not the framework; it is discovering the implemented/stubbed boundary, which only the spike reveals. Documentation is thin and release notes are uninformative, so institutional knowledge lives in the spike artifact and the diff-review habit, not in upstream docs. Budget onboarding accordingly: the second engineer learns from our notes, not from the package.

Decision framing. The scores are telling us two different things and both are true: opportunity 8.32 (high leverage if the capability set is real) against 0.445 overall (thin assurance that it is). The proportionate response is a timeboxed, throwaway-app spike producing a capability matrix and a schema diff, with a go/no-go gate based on that artifact. Green-light internal tooling, B2B reorder flows, event or merch stores, and pilot programs — use cases where a 1.0.x single-maintainer module is a proportionate bet. Red-light anything where checkout correctness carries revenue on day one without budget for the payment, tax, inventory, and idempotency work above.