Commerce Support Laravel Package

Product Decisions This Supports

Build vs. buy for the commerce backbone. This package is the conventions layer of a commerce suite, not a feature module. Adopting it is really a decision about whether our commerce domain will be built on an opinionated, first-party base (UUID keys, config-remappable tables, application-level cascades, Octane-safe state) instead of us hand-rolling those primitives in every service. That is a foundational, hard-to-reverse call — worth an explicit ADR rather than a sprint-level choice.

Roadmap sequencing for the commerce vertical. The package’s structure (per-package CONTEXT.md, docs contract of 01-overview → 99-troubleshooting, family frontmatter) tells us the suite is designed to be extended package-by-package. If we adopt, roadmap items should be sequenced as “add a sibling package” rather than “add a module,” which changes how we estimate and staff the work.

Admin surface and merchandising scope. The CommerceNavigation engine implies a concrete product bet: navigation, grouping, and sort are runtime-overridable per resource FQCN via config, and Filament packages are strictly adapters, never domain owners. That supports decisions like “ship one admin panel configurable per tenant/merchant without code changes” — a real product differentiator for multi-store or white-label commerce, and a scope lever for how much we build versus configure.

Data model and tenancy commitments. UUID primary keys, foreignUuid without database foreign-key constraints, and cascades enforced in model/booted() code are product-visible decisions. They buy portability (shardable, offline-friendly, sync-safe IDs) and cost us database-level integrity guarantees. Worth confirming with the data owner before it becomes the schema of record.

Multi-tenancy and isolation posture. The docs elevate “data isolation” above correctness and style in the rule hierarchy, and require owner-scoping on all queries and action handlers including tenancy. That directly supports a decision to serve multiple merchants/orgs from one deployment — or a decision to defer that capability if we don’t adopt.

Runtime and hosting strategy. The PHP 8.5+ / Laravel Octane / no-static-mutable-state baseline is a hosting and platform decision, not just a coding preference. It gates which environments we can deploy to and what our platform team must support.

Dependency governance and vendor risk. Zero stars, zero dependents, zero package score, MIT. This is effectively an unaudited first-party-style codebase. The decision it supports is whether our dependency policy permits a single-maintainer, pre-traction foundation — and if so, what our fork-and-own contingency looks like. Treat that contingency plan as a deliverable, not a footnote.

When to Consider This Package

Consider it when:

• We are already committed to the modern stack: PHP 8.5+, current Laravel, Filament v5. On older PHP or Filament v3/v4, the compatibility surface is against us before we start.
• We are building or extending a multi-package commerce suite, not a single app. The value is concentrated in cross-package conventions; a single-app team gets little from the routing/docs/monorepo scaffolding.
• We want our conventions enforced rather than debated — immutable date objects, Laravel Actions for cross-cutting orchestration, config-driven navigation, no DB foreign keys, no backward-compatibility shims. Adopting is partly a culture decision.
• We are comfortable forking and owning the code. Given the lack of ecosystem, the realistic model is “vendored base layer we maintain,” not “library we consume and upgrade.”
• We have an admin-heavy roadmap where a configurable navigation/permission/resource layer is a genuine time saver, and Filament v5 is our UI bet.
• The team is small enough that codified convention beats individual preference, and shipping speed outweighs public-reference availability.

Look elsewhere when:

• We need stable semantic versioning or any backward-compatibility guarantee. The stated policy is that breaking changes are allowed and BC is not required. For a package underneath our entire commerce domain, that is a material upgrade risk and must be priced in.
• We need community support, Stack Overflow answers, or third-party integrations. Zero stars and zero dependents mean no safety net, no ecosystem, no battle-testing signal.
• Our schema is already relational with enforced foreign keys and cascades. Migrating to application-level integrity is a real, error-prone change with no database backstop.
• We need audit-grade transactional integrity or regulatory reporting where DB-level constraints are the control.
• We must run on PHP 8.2–8.4, shared hosting, or a fixed Filament version.
• The commerce scope is narrow — one storefront, one catalog, one checkout. Cheaper to buy a mature commerce package or write the small amount of code we need.
• We cannot absorb a single-maintainer bus factor. No stars is not automatically disqualifying, but it means we are the maintainer of last resort.

Practical gate: a timeboxed spike (2–3 weeks) against one real vertical slice, with written exit criteria — one resource, one domain model with UUIDs and app-level cascades, one Filament panel with a runtime navigation override, verified under Octane. If the spike needs patching in more than one package to proceed, that is the signal that we own this codebase, and the decision should be re-scored on that basis.

How to Pitch It (Stakeholders)

For executives: We are evaluating an MIT-licensed Laravel commerce foundation that supplies the shared conventions for a multi-package commerce suite — ID strategy, data-integrity approach, admin panel composition, multi-tenant scoping, and runtime-configurable navigation. Its strategic appeal is white-label/multi-merchant configurability and consistency across future commerce modules, which could shorten time-to-market on the admin surface. Its maturity signals are weak: no community adoption, no dependents, one maintainer, and an explicit policy of permitting breaking changes. Recommendation: fund a short, scoped technical spike with defined exit criteria before any roadmap commitment. Do not adopt as a production foundation until we have either validated it in the spike or made a conscious decision to fork and own it.

For engineering: This is a base layer, not a feature set. It gives us UUID keys with app-level cascades, config-remappable tables, immutable dates, Laravel Actions as the orchestration primitive, Octane-safe state discipline, and a CommerceNavigation engine that lets us override any resource’s navigation at runtime by FQCN so Filament packages stay adapters rather than domain owners. It also imposes real constraints: PHP 8.5+, Filament v5, no database foreign keys, no backward-compatibility shims, and a documentation contract we must honor in the same pass as any public-behavior change. What we need from you in the spike is a cost estimate for two things: (1) working without DB-level integrity backstops, and (2) owning upgrades, since the project explicitly reserves the right to break us.

For the product owner: Adopting this makes our commerce platform configurable rather than custom, which is the differentiation story. The trade is that we take on maintenance risk and a modern-stack-only constraint. Ask for the spike to return a decision-ready answer on one question: can we ship one merchant-facing admin slice on this base without patching the base itself?