Tomato Products Module Laravel Package

Technical Evaluation

Architecture fit

• This is an admin-layer catalog module, not a commerce engine. It contributes Eloquent models, migrations, and Filament resources for products, categories, attributes, pricing fields, and stock fields. Orders, carts, checkout, tax, promotions, and inventory reservation are out of scope until proven otherwise.
• It fits a modular monolith on Laravel + Filament 3.x where TomatoPHP conventions are already in place. It does not fit an API-first/headless architecture with a non-Laravel admin, and it does not fit a microservice boundary without wrapping it.
• The correct architectural placement is a bounded catalog context: the module owns product persistence and the back-office UI; our application owns the domain contract (API surface, pricing rules, stock semantics) on top of it.

Integration feasibility

• Mechanically straightforward: Composer install, publish config/migrations/lang, php artisan migrate, verify provider registration, verify the Filament resource appears. A competent Laravel developer proves this in under a day.
• Real feasibility hinges on extension without forking: model observers, Resource::configureUsing() / Table::configureUsing(), subclassed Filament resources, published views, and lang/vendor/ overrides. All of these exist, which makes adoption viable; all of them are undocumented beyond the README, which shifts cost onto discovery.
• We will write our own API controllers, policies, and seeders. Budget for that explicitly — it is not a "free" layer.

Technical risk

• Bus factor 1. Single maintainer, v1.0.x, 1 GitHub star, 0 dependents, last release 2024-06-03 and it was translation strings only. There is no evidence of production usage anywhere, and no published support, security, or deprecation policy.
• Ecosystem coupling. The module is one node in a large tomatophp/* monorepo. Version drift across sibling packages is the most likely source of unplanned work; Filament major-version bumps will break resource registration before anything else.
• Schema opacity. Multi-variation and stock are advertised in the description but the depth is unverified: are variants a first-class model or attribute rows? Is stock a quantity field or stateful? Does the schema survive our own migrations on fresh installs? Each unknown is a potential mid-build surprise.
• Liveness signal is weak. Translation-only patch releases read as maintenance hygiene, not capability or hardening. We should not infer roadmap stability from them.

Key questions to answer before any commitment

1. What exactly is in the published migrations — variant model, price tiers, currency, stock semantics, media, statuses? Which of our required fields have no home?
2. What is the pinned Filament/PHP/Laravel constraint set in composer.json, and does it match our host application today and for the next two majors?
3. Does the module register global scopes, policies, or routes that conflict with ours? What are its service-provider side effects on boot?
4. How cleanly can the product model be extracted or replaced if upstream goes quiet — is the domain contract thin enough to swap?
5. Who owns the patch set internally, and is that person identified before adoption rather than after?
6. Is the transitive dependency tree and license provenance clean under our policy (MIT declared, but verify the full tree)?

Integration Approach

Stack fit

• Laravel (10/11-era) + Filament 3.x + PHP 8.x + TomatoPHP core. If we are not already on TomatoPHP, the cost of adopting the ecosystem — conventions, module registration, sibling packages for roles/permissions — dominates the cost of the products module itself. Mixing module ecosystems is where this gets expensive; treat "are we a TomatoPHP shop?" as a binary gate, not a gradient.
• If we are on Filament but not TomatoPHP, that is a legitimate middle path, but only if we accept the module as a standalone dependency and never expect sibling packages to Just Work.

Migration path

• Greenfield back office: adopt directly. Lowest friction, highest demo velocity.
• Existing catalog data: do not write to its tables with raw SQL. Import through the module's models, keep our canonical domain objects in application code, and treat the module as persistence + admin UI. This preserves the ability to re-platform persistence later.
• Existing admin UI: we inherit its UI opinions. Decide up front whether we reskin, extend, or coexist — coexisting admin surfaces for the same entity is a known source of editor confusion and data drift.

Compatibility

• Pin the exact tag, never main. Pin sibling tomatophp/* packages in lockstep; upgrade as a set, deliberately, with a smoke test.
• Verify the require block against our Filament version before any upgrade of either side.
• Audit every published migration as a schema change to our database, not as a package internal. Check reversibility and idempotency.

Sequencing

1. Gate 1 — Spike (2 days, time-boxed). Install at a pinned tag in a throwaway branch. Map our real catalog fields onto its schema field-by-field. Exercise our top three editor workflows in the admin. Produce a written gap list and an estimate in engineer-days.
2. Gate 2 — Build vs. buy decision. Adopt only if the gap estimate is materially below the internal build estimate and we have named an owner for the patch set. A translation-only release should not move this decision.
3. If adopt — harden. Register our own policies and permissions, publish and override translations via the vendor path, build the API layer and seeders on top of its models, add a thin adapter so the module is not called directly from controllers.
4. Extend, don't fork. Add columns and scopes through Filament configuration hooks and observers. Any vendor-directory edit will be destroyed by the next patch release.
5. Exit plan before first production write. One page: how we fork, how we carry patches, what the extraction boundary is.

Explicit scope fence

• Keep orders, carts, tax, payments, and inventory reservation out of this integration. If the roadmap depends on those, this package is upstream of the problem, not a solution to it, and assembling a commerce engine from catalog primitives is a decision we would be making by accident.

Operational Impact

Maintenance

• We own the patch set. Budget a recurring, small but non-zero maintenance line: dependency bumps, Filament upgrades, translation overrides, and the occasional upstream-fix backport.
• Changelogs are terse ("update translation"). Read the compare diff before trusting the note — it is the only reliable scope signal.
• Translation releases are safe to pull but will overwrite anything edited inside the package directory. Enforce a rule: translations are only ever overridden at lang/vendor/tomato-products-module/.

Support

• Community-only, no SLA, no security disclosure process, single maintainer. This is acceptable for internal back-office tooling; it is not acceptable for anything customer-facing or revenue-critical without a documented internal owner.
• The primary mitigation is architectural, not contractual: a thin adapter layer between our application and the module's models. That converts "upstream abandoned" from a rewrite into a bounded migration project.

Scaling

• The admin CRUD path scales with the database like any Filament resource; it is not the bottleneck. Catalog read scaling (caching, search index, CDN for media) is ours to design and is independent of this package.
• The genuine scaling risk is stock and price concurrency. If our roadmap needs accurate inventory under concurrent writes, this module does not provide the locking or reservation semantics — we must impose them, or keep transactional inventory outside the module's tables entirely.

Failure modes to watch

• Filament major bump breaks resource registration first, usually as resources silently disappearing from the panel.
• Silent resource absence from any of: provider not registered in bootstrap/providers.php or module manifest, canViewAny policy returning false, config enabled flag off. Codify this as a runbook item rather than a debugging ritual.
• Schema re-introduction on fresh installs after we have altered the module's tables with our own migrations — the package may restore its own columns. Any schema change we make must be reconcilable with a fresh module migrate.
• Dependency drift across the tomatophp/* set from a single unpinned composer update.
• Fork rot — adopting and then never pulling upstream fixes, which quietly converts a supported dependency into a private one.

Ramp-up

• A Laravel developer is productive in the module within one to two days; genuinely fluent customization in Filament takes about a week. Learning TomatoPHP module conventions from scratch is the long pole if we are new to the ecosystem.
• Knowledge concentration is the real ramp-up risk on a single-maintainer dependency: the seams (how we extend, how we would extract) must be documented in-repo, not held by the person who ran the spike.
• Onboarding cost is low and asymmetric — cheap to learn, expensive to learn after the person who chose it has left.