Tomato Inventory Module Laravel Package

Technical Evaluation

Architecture fit

• tomatophp/tomato-inventory-module is a domain module in the TomatoPHP ecosystem — Laravel + Filament admin panels under a module-per-capability convention. Architecturally it occupies an inventory bounded context: products/SKUs, stock levels, warehouses/locations, and stock movements, surfaced as Filament resources plus service classes.
• Strong fit when we already run Laravel + Filament and ideally the wider TomatoPHP module set (roles/permissions, navigation). The module then inherits our service-provider, migration, and resource conventions instead of imposing a new pattern.
• Weak fit if we run a bespoke admin layer or an API-first/headless architecture — we would adopt its UI and data conventions wholesale to extract its value, and the Filament coupling becomes a liability rather than a feature.
• Inventory is genuinely cross-cutting (orders, purchasing, fulfilment). The decisive architectural question is whether this module is a self-contained, auditable stock ledger or a thin CRUD layer that mutates a quantity column over someone else's products table. That distinction determines whether it can be the system of record for stock or merely a UI over one.

Integration feasibility

• Installation is cheap and well-trodden: composer require, publish config/migrations, register with the TomatoPHP module loader, run migrations, point at or seed product data.
• The real effort is data reconciliation, not installation: mapping our existing product/SKU master to the module's schema, and backfilling opening balances as auditable movement records rather than direct quantity writes.
• Filament major-version coupling is the gating check. Filament v3 → v4 is a breaking change across resources and widgets; we must confirm the module's declared filament/filament, laravel/framework, and php constraints before committing engineering time.
• TPM effort framing: a 2–3 day sandbox spike answers most feasibility questions; 2–4 weeks gets us to a staging integration with a real catalog and a reconciled opening balance.

Technical risk

• Release-notes risk (high): the v1.0.0 changelog contains nothing but a compare link. There is no upgrade guide, deprecation policy, or versioning commitment. "1.0.0" here means first tag, not API stability — we should not present it to stakeholders as a maturity signal.
• Bus-factor risk (moderate-high): single maintainer (@abdelmjid-saber), small community-driven ecosystem, 0 stars and 0 dependents. Zero dependents is the notable number — it means no public downstream battle-testing and no network effect if the maintainer steps away.
• Schema-coupling risk (moderate): the module migrates into the host database. A 1.0.0 schema can change in 1.1.x with no migration path for accumulated stock history; our data lives in its tables.
• Correctness risk (moderate): stock ledger math — reservations, backorders, multi-warehouse transfers, adjustments, costing method — is precisely where inventory packages most often fall short. Unverified at this tag.
• Security surface (low): internal admin domain, but permission/policy coverage and tenancy scoping must be explicitly checked before exposure to warehouse staff.
• Legal (low): MIT license is clean for commercial internal use.

Key questions

1. What are the declared php, laravel/framework, and filament/filament constraints in composer.json?
2. Does it own an auditable, reversible stock-movement ledger, or just mutate a quantity column?
3. Multi-warehouse, lot/serial/batch, and unit-of-measure support — in scope or absent?
4. Is a costing method (FIFO / weighted average) implemented, or explicitly out of scope?
5. Does it define its own products table or integrate with an existing catalog? Any foreign keys into host tables we don't control?
6. Test coverage and CI status at the v1.0.0 tag; are migrations reversible (down() present)?
7. Is there any maintainer-stated roadmap, and what is typical issue responsiveness?
8. If the module stalls, are we willing to fork and own it? (Product decision, not just engineering.)

Integration Approach

Stack fit

• Requires Laravel with Filament; the broader TomatoPHP stack is optional but assumed for navigation and access control (roles/permissions).
• Best evaluated as one module inside a modular monolith, not a standalone service. If we are multi-tenant, confirm tenant scoping exists or can be layered on before we design around it.
• If our product is an API-first SPA, budget for either adopting Filament for the admin surface or building a thin API over the module's service layer — the latter is real, unbudgeted work.

Migration path

• Phase 0 — Spike (2–3 days, gate: go/no-go): install in a throwaway Laravel app pinned to our target versions, run migrations, exercise product creation, stock movement, adjustment, and low-stock reporting. This is the cheapest possible way to answer the key questions and is the only artifact that can move our confidence above medium.
• Phase 1 — Staging integration (gate: data-fit sign-off): integrate on a branch against a copy of our catalog; design the SKU mapping and an opening-balance import that writes real movement records. No direct quantity seeding.
• Phase 2 — Internal beta behind a feature flag: single warehouse, no costing, legacy inventory source remains authoritative; nightly reconciliation reports prove parity before any promise is made to the business.
• Phase 3 — Full rollout, then decommission legacy tracking. Deliberately last.
• There is no migration path from the module (no 0.x line, no prior tags) — this is greenfield adoption, so exit cost equals the cost of adoption: our stock history would live in its schema. That is the single most important fact for the buy-vs-fork decision.

Compatibility

• Pin the exact v1.0.0 tag and commit the lockfile. Do not float on ^1.0 until a 1.0.x patch history demonstrates release discipline.
• Verify the Filament and Laravel major versions explicitly; accept that we will be pinned to whatever the module supports rather than upgrading the admin panel independently on our own cadence.
• Audit the composer manifest for PHP extension and database requirements (JSON columns, full-text indexes) against our target environments.

Sequencing

1. Manifest and README audit (no code, ~half a day) — version constraints, migration list, resource inventory.
2. Sandbox spike with real-shaped data — the decision gate.
3. Data-mapping and opening-balance design — jointly owned by engineering and whoever owns catalog data quality today.
4. Internal admin beta — single warehouse, no costing, reconciliation running nightly.
5. Full rollout with reconciliation reporting, and only then decommission the legacy inventory source.

Each step should have a named owner and a written exit criterion; the sequence exists to keep us from discovering a ledger-math gap after warehouse staff have been trained on it.

Operational Impact

Maintenance

• We inherit an external dependency's release cadence from a single maintainer with one tag. Realistically, budget for us becoming the de facto maintainers via a fork if activity stalls — that is a contingency to price now, not a surprise to absorb later.
• Filament or Laravel major upgrades become blocked-on-upstream items in our upgrade calendar. This is the recurring operational tax of the choice, and it should be visible on the roadmap rather than discovered during a routine maintenance window.
• Ongoing cost is low while our domain model fits. It rises sharply the moment we need lot tracking, costing, or complex transfer semantics the module lacks — because patching means owning a fork, not writing a feature.

Support

• Support path is GitHub issues only; no commercial SLA, no vendor escalation channel, no security-response commitment visible. Set that expectation internally before anyone commits to the business.
• Nominate a named internal owner (a backend engineer) and document the fork procedure — remote setup, patch policy, and who approves upstream merges — as part of the adoption checklist, not afterward.

Scaling

• Inventory tables grow with movement volume, not user count — expect a high-write table. Confirm indexes on SKU/warehouse/timestamp and that stock-level reads are aggregated rather than recomputed per row.
• Admin UI is Filament resource-based; large catalogs need pagination, search indexing, and queued exports. Validate against our real catalog size before promising warehouse staff a fast list view.
• Concurrency is the sharp edge: multiple users adjusting the same line require row locking or atomic decrements. Unverified at 1.0.0 — test this explicitly in the spike with two concurrent sessions, not just single-user happy paths.

Failure modes

• Stock drift from non-atomic updates or from direct quantity edits bypassing the ledger — mitigate by policy and by only ever writing movements.
• Silent breakage on a Laravel/Filament upgrade during a routine maintenance window, with no upstream fix available.
• Upstream abandonment leaving us on an unsupported framework major with a growing fork backlog.
• Failed rollback on a schema with no down() migrations — mitigate with mandatory pre-migration backups.
• Multi-warehouse transfer bugs double-counting or losing stock — reconcile totals nightly throughout beta and treat any variance as a release blocker.

Ramp-up

• Engineering: ~1 day for a Laravel/Filament-fluent developer to read the module and run the spike; the genuine learning curve is the domain distinction between movements and levels, not the code.
• Ops/warehouse staff: ~1 hour of training — Filament admin is conventional CRUD. The real effort is process change (how adjustments are requested and approved), not UI.
• TPM/analyst: ~1 hour to review release history and open issues. Because the release contains no substantive notes, this assessment stays at medium confidence until the spike produces data; don't let it masquerade as high confidence in roadmap documents.

Recommendation

• Adopt conditionally: fund a time-boxed spike, not a commitment. Do not treat the v1.0.0 tag as evidence of maturity — treat it as the first data point in a release history that does not yet exist.
• Define the go/no-go criteria before the spike: ledger integrity under concurrent edits, a clean migration path for our catalog, and confirmation that our hard requirements (multi-warehouse, tenancy, costing) are either in scope or genuinely out of scope for v1.
• Re-assess at the next upstream tag or once the key questions are answered. If the spike surfaces a gap in ledger or concurrency correctness, the correct product decision is build-or-extend in-house, not patch-and-hope.