Tomato Ecommerce Laravel Package

Product Decisions This Supports

• Build vs. buy vs. adopt-a-module for the first commerce release. This reframes the usual "custom build vs. Shopify/BigCommerce" trade-off into a third option: drop an admin-first commerce module into an existing Laravel/Filament monolith we already run. Worth evaluating when the roadmap is "catalog, cart, checkout, and order visibility in weeks" and the team already lives in Filament daily — the integration cost is real but front-loaded and familiar, versus a hosted platform's per-transaction and integration surface.

• Defining what "MVP commerce" means for v1. The stated capability surface — products and categories, cart, checkout, orders with status tracking, Filament admin, extensible Laravel architecture – maps to a PRD skeleton cleanly. The PM's job is to mark every line as assumed present, unverified. The release history (v1.0.8 is a single "update icon" commit) provides zero evidence that payments, tax, shipping rates, refunds, or inventory reservation are implemented rather than stubbed. Treat the description as a vendor claim, not a feature list.

• Roadmap sequencing: back office first, storefront second. The package is explicitly admin-panel-first — models are shaped around Filament resources, not a headless API contract. That supports a phased roadmap: phase one operational (catalog management, order visibility, manual fulfillment), phase two customer-facing checkout. It argues against a roadmap where a headless or API-first storefront is the headline deliverable in the same quarter.

• Make vs. integrate on payments, tax, and shipping. "Extensible architecture for custom pricing, payments, and workflows" is the package's own framing of the boundary. That supports a decision to keep payments and shipping as our domain, behind our own gateway adapters, rather than promising a turnkey payment story. Budget a service layer explicitly — no stakeholder should read "full e-commerce system" as "Stripe is included."

• Low-stakes commerce use cases. Order desks, B2B reorder flows, event or merch stores, and pilot programs are the decisions where a 1.0.x, single-maintainer package is a proportionate bet — small blast radius, no revenue-critical SLA, fast time-to-value. The same package is a much worse bet as the backbone of a primary revenue channel.

• Buy-in for the spike as a decision gate. The most valuable decision this package supports is a cheap, timeboxed evaluation: a capability matrix (implemented / partial / stubbed) built in a throwaway app, plus a schema diff against our target database. That artifact — not a demo — is what the go/no-go meeting should be based on. A one-week spike that produces "here's the five things we'd have to build ourselves" is a win even if the answer is no.

• Explicitly out of scope, worth stating up front. Headless/API-first storefronts, multi-tenant or multi-vendor marketplaces, and any team that wants to own the domain model outright. If those are on the roadmap, close this decision early rather than carrying it as a maybe.

When to Consider This Package

Consider it when all of the following hold:

• We are on Laravel + Filament already, and ideally already running tomatophp/* modules. Without that, the admin integration — the package's main value — is worth nothing to us.
• The commerce need is internal-facing or low-volume: order desks, B2B reorders, merch, pilots, an MVP we expect to outgrow.
• We accept a back-office-first architecture and will build the customer-facing storefront and payment integration ourselves, behind our own service layer.
• We can afford a named engineer owning upgrades: because release notes are one-line commits, every bump requires reading git diff on src and database personally. That's a recurring cost, not a one-off.
• We can pin the exact tag (1.0.8, not ^1.0) and live with the constraint lockstep of the TomatoPHP family.
• We have no existing products / carts / orders tables — or are willing to run the package's tables alongside and treat migration as a later project.

Look elsewhere when:

• Commerce is the revenue channel. Three GitHub stars, zero dependents, a single-maintainer ecosystem, a last release in April 2024, and one-commit changelogs are not a foundation for money-critical paths. The unsolved hard problems — inventory oversell under concurrency, idempotent payment webhooks, tax calculation, refund state machines — all land on us anyway.
• We need a headless API as a first-class contract, multi-currency/multi-region, or multi-vendor. The architecture is not shaped for it.
• We need payments, tax, and shipping out of the box. They are almost certainly not here; buy a platform rather than assemble one from a starter.
• We can't absorb a surprise-breaking upgrade. If a white-screened admin page on a Friday is not an acceptable risk, choose a package with a real changelog and multiple maintainers.
• Someone else's release cadence is a hard blocker — e.g. we ship compliance-sensitive changes on a fixed schedule and can't wait on a single maintainer.

How to Pitch It (Stakeholders)

To executives: There's a credible shortcut for the back-office half of commerce — catalog, cart, orders, admin screens — from an admin-panel-first Laravel module. It's MIT-licensed, so there's no vendor fee or lock-in, and the adoption risk is low: MIT license, no dependents to break, drop-in behind a feature flag. But it's a starter, not a platform. It's a single-maintainer project with three stars, no release since April 2024, and one-line changelogs. Recommendation: fund a one-week spike, not an adoption. Output is a capability matrix telling us exactly what's built versus stubbed, and a schema diff against our database. That's a cheap way to buy information before committing a quarter. Don't read "full e-commerce system" as "payments included" — payments, tax, shipping, and inventory integrity are ours either way.

To engineering: Treat it as a back-office toolkit, not a commerce engine. Keep its models as persistence; write a thin App\Services\CheckoutService that owns cart → order → payment so upstream patch churn hits one file instead of every controller. Wrap, don't extend; add new migrations rather than editing published ones. Integrate payments behind a PaymentGateway contract with charge / refund / verifyWebhook, create orders in pending, confirm from a queued idempotent webhook. Add a status enum with guarded transitions — assume no state machine ships. Assume no row locking on stock until proven otherwise. Pin 1.0.8 exactly, commit the lockfile on its own branch, and treat every tomatophp/* bump as a family-wide rehearsal. First hour: read composer.json constraints, then database/migrations, then the Filament resources. Then walk the golden path by hand before writing a line of integration code.

The one metric that decides it: how many rows in the capability matrix read "stubbed" or "we'd have to build this." If the answer is more than two or three of {payments, tax, shipping, refunds, inventory reservation, storefront}, the word "e-commerce system" is doing more work than the code is.